How to use Amplitude APIs to export custom analytics data for reporting

Want your Amplitude data in a spreadsheet, dashboard, or somewhere your boss can actually read it? You’re not alone. Amplitude is great at tracking what users do, but getting exactly the data you want—out of its UI and into your own reports—takes some real work. This guide is for folks who want more than canned dashboards and are ready to wrangle the Amplitude APIs directly. I’ll walk you through it, point out the gotchas, and tell you where not to waste your time.

Why bother with Amplitude APIs?

Let’s be honest: Amplitude’s web interface is fine for basic charts, but if you want custom reports, automate things, or mash data with other sources, you’ll need its APIs. Here’s where APIs shine:

  • Automate exports for regular reporting (no more screenshotting graphs).
  • Access raw event data for deeper analysis in SQL, Python, R, etc.
  • Integrate with your own BI tools or data warehouse.
  • Avoid UI limits (like download caps or awkward CSV formats).

Some things the APIs don’t do well? Real-time data (there’s lag), and the docs can be vague. But you can get what you need if you know where to look.

Step 1: Figure Out What Data You Really Need

Before you even touch an API key, get specific:

  • Which product, project, or environment is your data in?
  • Do you need raw events (every click, every property), or just aggregated numbers (like DAUs, funnel completions)?
  • What’s the time range?
  • Are you joining Amplitude data with other sources?

Pro tip: The more precise you are now, the less you’ll want to tear your hair out later.

Step 2: Get API Access and Keys

Amplitude’s APIs need authentication. Here’s what to do:

  1. Log in to Amplitude.
  2. Go to Settings > Projects > select your project.
  3. Find your API Key and Secret Key.
    • The API key identifies your project.
    • The Secret Key is what you’ll use to authenticate requests.

Don’t share your Secret Key—it gives full access. Store it in an environment variable or a password manager.

Step 3: Choose the Right API

Amplitude has a few APIs, and picking the wrong one wastes hours. Here’s the real talk:

1. Export API (Raw Events)

  • What it does: Dumps raw event data (every event, every property).
  • Best for: Deep dives, custom analysis, pushing to warehouses.
  • Limits: Max 30 days per request; data is delivered as gzipped JSON files; not real-time (usually 1-3 hours delay).

2. Dashboard REST API (Aggregated Data)

  • What it does: Pulls processed metrics—charts, cohorts, queries you’ve already built in the UI.
  • Best for: Automating reports you already see in Amplitude dashboards.
  • Limits: Not as flexible as Export API, but easier for basic needs.

3. User Activity API

  • What it does: Fetches all events for a single user.
  • Best for: Investigating specific user journeys, debugging.

Ignore the HTTP API for exporting data—it’s for sending data in, not pulling it out.

Step 4: Exporting Raw Events with the Export API

Let’s do a basic export of raw events. This is the most flexible, but you’ll need to process the data yourself.

How it works

  • Make a GET request to:
    https://amplitude.com/api/2/export?start=YYYYMMDDTHH&end=YYYYMMDDTHH
    • Example: start=20230501T00&end=20230502T00 (exports data from May 1st, 2023, 00:00 to May 2nd, 2023, 00:00)
  • Use HTTP Basic Auth with your API key as the username and Secret Key as the password.

Example using curl

bash curl -u API_KEY:SECRET_KEY \ "https://amplitude.com/api/2/export?start=20230501T00&end=20230502T00" \ -o events.zip

You’ll get a ZIP file of gzipped JSON files, one per hour.

What’s inside

Each file contains event objects. It’s verbose—think thousands of lines per day for busy apps.

Tip: Use Python, jq, or your favorite scripting tool to filter and process these files. If you try to load them directly in Excel, you’ll probably crash it.

Gotchas

  • Time limits: Max 31 days per export, but it’s safer to do a week at a time.
  • Lag: Data is usually 1–3 hours behind real time.
  • Fields: Not all event properties are always present. Amplitude’s event schema can be messy, especially if tracking changed over time.

Step 5: Exporting Aggregated Data with the Dashboard REST API

If you just want numbers or chart results, not every raw event, use the Dashboard REST API.

Find Your Chart’s Query ID

  • In Amplitude, open the chart you want.
  • Copy the URL. It’ll look like: https://analytics.amplitude.com/org/project/chart/abcdef
  • The last bit (abcdef) is your chart ID.

Make the API Request

Use this endpoint:
https://amplitude.com/api/2/chart/{chart_id}/data

Example with curl:

bash curl -u API_KEY:SECRET_KEY \ "https://amplitude.com/api/2/chart/abcdef/data"

This gives you the same data the UI shows, in JSON. You can script this to run daily or weekly.

Limitations

  • You can’t change the chart’s filters or time range via API—it always uses what’s saved in the UI.
  • Not all chart types are supported. Some complex visualizations or custom formulas might not export cleanly.

Step 6: Useful Patterns and Tips

Automate your exports

  • Use a daily or weekly cron job (with a script in Python, Bash, etc.).
  • Store API keys securely—never hardcode them in scripts you share.
  • Rotate keys if you think they’ve leaked.

Processing large files

  • For raw exports, process files in batches. Tools like Python’s pandas or command-line jq help a lot.
  • Compress or archive old data. Raw event files add up quickly.

Joining with other data

  • Amplitude IDs are unique per user and event, but mapping to your own user IDs can be tricky if your tracking isn’t consistent.
  • If you need to join with other databases, make sure you’re exporting the right identifying fields.

Dealing with API limits

  • Amplitude enforces rate limits. If you’re downloading a lot, build in retries and back-off logic.
  • Don’t hammer the API with huge date ranges—small, regular exports work better.

Step 7: What to Ignore (or Not Bother With—Yet)

  • Trying to get real-time data. You’ll always be a couple hours behind. If you need real-time, Amplitude isn’t built for that.
  • Over-engineering. Start with basic exports and see what you actually use.
  • Third-party Amplitude wrappers. Most just call the same APIs. Write your own scripts unless you need something fancy.

Step 8: Security and Compliance

  • Treat export scripts and data as sensitive—raw events can include user info.
  • Clean up old exports to avoid data leaks.
  • Don’t send API keys in URLs or public forums (sounds obvious, but you’d be surprised).

Wrapping Up: Keep It Simple, Iterate

Exporting custom analytics data from Amplitude isn’t rocket science, but it can get messy fast if you try to do everything at once. Start with small, clear exports—get comfortable with the raw data and the quirks of each API. Only build what you actually need. And if you hit a wall, don’t be afraid to ask for help or check if someone already solved your problem in a public repo or forum.

Get your exports working, automate the boring stuff, and spend your time on analysis, not data-wrangling. Good luck!