---
title: Export API
description: Export your project's event data.
product: analytics
lang: en
token_estimate: 2152
---
# Export API

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

## Plan availability

Export API is available on all plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details.

_Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._

## 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:

| Data residency | Base URL |
| --- | --- |
| Default | `https://amplitude.com` |
| EU | `https://analytics.eu.amplitude.com` |

## 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](https://amplitude.com/docs/data/destination-catalog/amazon-s3#run-a-manual-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

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

#### HTTP

```bash
GET /api/2/export?start=<starttime>&end=<endtime> HTTP/1.1
Host: amplitude.com
Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
```

#### Example: Get data for a period

Export activity data from midnight on January 1, 2022 through the hour starting at midnight on January 27, 2022, in UTC.

#### cURL

```curl
curl --location --request GET 'https://amplitude.com/api/2/export?start=20220101T00&end=20220127T00' \
--header 'Authorization: Basic YWhhbWwsdG9uQGFwaWdlZS5jb206bClwYXNzdzByZAo'
```

#### HTTP

```bash
GET /api/2/export?start=20220101T00&end=20220127T00 HTTP/1.1
Host: amplitude.com
Authorization: Basic YWhhbWwsdG9uQGFwaWdlZS5jb206bClwYXNzdzByZAo
```

## Query parameters

| Name | Required | Description |
| --- | --- | --- |
| `start` | Yes | First hour included in data series, formatted `YYYYMMDDTHH`. For example, `20220201T05`. |
| `end` | Yes | Last hour included in data series, formatted `YYYYMMDDTHH`. For example, `20220201T05`. |

## 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:

| Limit | Default |
| --- | --- |
| Concurrent requests | 4 |
| Requests per hour | 360 |

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](#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.

> **Note:**
>
> Amplitude groups events before November 12, 2014 by day instead of by hour.

### Response schema

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

```json
{
 "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

| Code | Meaning | What to do |
| --- | --- | --- |
| `200` | The request succeeded and returns a ZIP archive. | Download and validate the complete archive before processing it. |
| `400` | A required parameter is missing, a date has an invalid format, or the export exceeds the documented 4 GB size limit. | Correct the request. For a size error, shorten the range. If one hour exceeds the limit, use the [Amazon S3 destination](https://amplitude.com/docs/data/destination-catalog/amazon-s3#run-a-manual-export). |
| `401` | The Basic authentication header is missing or malformed. | Send a valid Basic authentication header. |
| `403` | The API key or secret key is invalid, or Amplitude has blocked the API key. | Check the credentials and project region. Resolve blocked-key access before retrying. |
| `404` | No export files exist for the requested range. | Check the project and UTC upload-time range. For recent data, wait for export availability and retry. |
| `429` | The request exceeds a rate or concurrency limit. | Reduce concurrency or request frequency and retry with backoff. |
| `504` | The export timed out. | Retry with a smaller range. For large exports, use the Amazon S3 destination. |

### 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.