Export API

Regions

The base URL depends on your project's data residency. For EU projects, replace the default base URL in the examples with the EU base URL in this table.

The https://analytics.amplitude.com hostname serves the Analytics web app (browser UI). For REST requests, use the base URL for your project's data residency:

Considerations

• The date range uses the event data's upload time on Amplitude servers (server_upload_time). The Export API returns events timestamped in UTC. You can export data within 2 hours after Amplitude servers receive it. For example, data sent between 8 and 9 PM begins loading at 9 PM and becomes available through the Export API at 11 PM. Platform reporting has no delay. Only exports have a delay.
• The Export API doesn't support cross-project views, because the view doesn't own any data. To export all the data in the view, call the Export API on the underlying projects that ingested the data.
• The size limit is 4 GB. If the export exceeds 4 GB, the request returns a 400 response. Choose a smaller time range. If one hour of data exceeds 4 GB, use the Amazon S3 export.
• To export a whole day, use T00 to T23. For example, GET 'https://amplitude.com/api/2/export?start=20220101T00&end=20220101T23'.
• The maximum period you can query at once is 365 days.

Request

GET https://amplitude.com/api/2/export

Authenticate with HTTP Basic authentication. Use the project's API key as the username and its secret key as the password. For a raw HTTP request, base64 encode the string api_key:secret_key after Authorization: Basic. cURL's -u option encodes the credentials for you.

curl --location --request GET 'https://amplitude.com/api/2/export?start=<starttime>&end=<endtime>' \
-u '{api_key}:{secret_key}'

Query parameters

Rate limits

The Export API uses a separate limit from Dashboard REST API queries. The default limits apply to requests using the same project API key:

Project or organization overrides can change these defaults. Exceeding a limit returns HTTP 429. The error identifies the exceeded limit as rate or concurrent. Coordinate workers that share credentials so they share the same request budget.

Data availability and consistency

Both start and end include the specified hour and use UTC. For example, start=20220201T05&end=20220201T05 exports one hour. For consecutive requests, start the next range one hour after the previous range's end to avoid overlapping hours.

Export ranges select events by server_upload_time, not event_time. A late event with an earlier event timestamp belongs to the hour when Amplitude uploaded it. Use upload-time ranges when maintaining an export checkpoint.

Allow for the export delay described in Considerations before treating an hour as complete. A 404 for a recent hour means no export files exist for that request yet; it doesn't establish that Amplitude received no events. Retry the hour after the availability delay.

Don't treat separate export requests as a single snapshot or assume retries return identical archive bytes. Validate the complete ZIP download before advancing your checkpoint. If you retry an overlapping range, deduplicate events in your destination rather than assuming the export request deduplicates previous downloads.

Response

The response is a ZIP archive of JSON files. Depending on data volume, the archive can contain several files per hour. The API returns a 404 response if the requested time range contains no data.

Response schema

Each file contains one event JSON object per line, with the following schema:

{
 "server_received_time": UTC ISO-8601 formatted timestamp,
 "app": int,
 "device_carrier": string,
 "city": string,
 "user_id": string,
 "uuid": UUID,
 "event_time": UTC ISO-8601 formatted timestamp,
 "platform": string,
 "os_version": string,
 "amplitude_id": long,
 "processed_time": UTC ISO-8601 formatted timestamp,
 "version_name": string,
 "ip_address": string,
 "paying": boolean,
 "dma": string,
 "group_properties": dict,
 "user_properties": dict,
 "client_upload_time": UTC ISO-8601 formatted timestamp,
 "$insert_id": string,
 "event_type": string,
 "library": string,
 "amplitude_attribution_ids": string,
 "device_type": string,
 "start_version": string,
 "location_lng": float,
 "server_upload_time": UTC ISO-8601 formatted timestamp,
 "event_id": int,
 "location_lat": float,
 "os_name": string,
 "groups": dict,
 "event_properties": dict,
 "data": dict,
 "device_id": string,
 "language": string,
 "country": string,
 "region": string,
 "session_id": long,
 "device_family": string,
 "sample_rate": null,
 "client_event_time": UTC ISO-8601 formatted timestamp,
}

Status codes

Retry handling

Use the HTTP status to decide how to handle a failure. Error bodies can vary; don't assume every failure returns JSON or a fixed message.

For 429, network failures, and transient 5xx responses, use exponential backoff with jitter and a bounded retry count. If the response includes Retry-After, honor it. Otherwise, use your client's backoff policy. Inspect the 429 error to distinguish a concurrency limit from an hourly rate limit; an immediate retry doesn't resolve an exhausted hourly budget. Don't retry authentication or validation failures until you correct the request.