Required Event Argument Keys

You must include the following keys within the event argument:

Note: For iOS devices, you can send either the IDFA or the IDFV but you must send at least one.

Optional Event Argument Keys

These optional keys are available.

Get a discoverable cohort using its cohort_id.

This is phase one in the download a cohort operation. The request_id returned in the response is used to poll export status.

Batch Event Upload

Use this request to bulk upload events to Amplitude.

If you have used our HTTP API before, note that there are two minor but important differences in your POST request to /batch.

• Content-type must be application/json.
• The key for the events payload is events plural, not event singular.

Properties

Responses

Code 429 Explained

When a request is rejected with a 429 status, it means that a device or user in that request was throttled. Details about which can be found in the error response data. Logging the response lets you investigate which users or devices were the cause of throttling.

Because device_id and user_id are the attributes that determine throttling, partitioning work on one of these attributes will help isolate throttling to a specific partition of work. This way partitions which are not being throttled can still make progress while the throttled partitions are blocked by throttling.

EPDS and EPUS

Amplitude measures the rate of events for each deviceid and each userid for a project, and refer to those rates as events per device second (EPDS) and events per user second (EPUS) respectively. These values are both averaged over a period of 30 seconds.

For example, to reach an EPDS limit of 1000 requires that a device sends 30,000 events in a 30-second period for the device to be throttled and receive HTTP status 429.

In general, your app shouldn't measure EPDS or EPUS itself. Send requests to Amplitude as fast as possible. When you receive a 429, wait for a short period (for example, 15 seconds) before trying to send that request again.

Daily Limit

In addition to the per-second limit, there is daily limit to prevent against spam and abuse. This limit is rarely exceeded. Events starts counting toward the daily limit after Amplitude determines that a user/device is spamming the system. After the threshold is reached, a daily limit of 500,000 events uploaded per rolling 24 hours is enforced. The 24 hour rolling period applies in one-hour intervals. The daily limit applies for each deviceid and each user_id for a project.

The daily limit is independent of the EPDS/EPUS. Once a user or device has hit the 500,000 event daily limit for a particular project, any batches uploaded containing the user or device is rejected. In those cases, the request returns a 429 response with a body indicating “exceeded_daily_quota_users” or “exceeded_daily_quota_devices” with list of deviceIds and userIds. Retry the batch when there are less than 500,000 events uploaded for a user or device in the previous 24 hour period.

Poll the request status. This is the second phase in a cohort download operation.

Get all discoverable cohorts for an app. The id returned for each cohort is used to get a single cohort.

Each COHORT_OBJECT has this schema:

{
    "lastComputed": timestamp,
    "owners": string[],
    "description": string,
    "definition": { COHORT_DEFINITION },
    "published": boolean,
    "archived": boolean,
    "name": string,
    "appId": string,
    "lastMod": timestamp,
    "type": string,
    "id": string,
    "size": integer
}

For small cohorts, the response body contains cohort data.

For large cohorts, the data must be downloaded. If the cohort is large, the response redirects with a 302 response code to a pre-signed Amazon S3 download URL. The download URL is valid for one minute, and should be accessed immediately.

The API request link (https://amplitude.com/api/5/cohorts/request/:requestId/file) is valid for seven days. During the seven days, you can make the same request repeatedly to get a new S3 download link. Each S3 link is valid only for one minute.

Most clients used to send API requests automatically download the data from the S3 link. If your API client doesn't automatically download the cohort from the S3 link, you have one minute access it manually.