HTTP V2 API

Considerations

Keep the following in mind as you use the HTTP V2 API.

Upload limit

For Starter plan customers:

Limit your upload to 100 batches per second and 1000 events per second. You can batch events into an upload, but Amplitude recommends not sending more than 10 events per batch. Amplitude expects fewer than 100 batches per second, and the 1000 events per second limit still applies.

For customers on Growth and Enterprise plans:

Keep request sizes under 1 MB with fewer than 2000 events per request. When you exceed these size limits, you get a 413 error.

If you have high volume and concerned with scale, partition your work based on device_id or user_id. This ensures that throttling on a particular device_id (or user_id) doesn't impact all senders in your system. If you use a proxy service to send events to Amplitude, make sure that throttling forwards to your clients, instead of letting spammy clients slow down a partition of work in your system.

Information for partner integrations

If you have an event ingestion integration with Amplitude, you need to send your integration's assigned partner ID in the event payload.

For help finding your integration's partner ID and a payload example, see Create an Event Ingestion Integration.

All-zero device IDs: Limit Ad Tracking enabled

As of iOS 10, Apple replaces the Identifier for Advertiser (IDFA) with all zeros if the user enables Limit Ad Tracking. Because all events require a device ID, Amplitude drops device IDs of all zeros and returns an error on the request.

If you are passing the IDFA as the device ID, first run a check on the IDFA value. If it's all zeros, pass a different value for the device ID, such as the Identifier for Vendor (IDFV).

Windows OS

If you are using a Windows operating system, then you may have to replace all single quotes with escaped double quotes.

String character limit

All string values, like user_id, event, or user property values, have a character limit of 1024 characters.

Set date values

Amplitude compares dates as strings, so it's best to use the ISO 8601 format (YYYY-MM-DDTHH:mm:ss). This format lets you perform date comparisons, (for example: '2016-01-31' > '2016-01-01'). Comparison also works for datetime values in this format (for example: '2017-08-07T10:09:08' > '2017-08-07T01:07:00').

Set time values

You must send the time parameter in each event as millisecond since epoch. Any other format (such as ISO format) results in a 400 Bad Request response.

Event deduplication

It's highly recommended that you send an insert_id for each event to prevent sending duplicate events to Amplitude. Amplitude ignores subsequent events sent with the same insert_id on the same device_id (if the event has a device_id value) in each app within the past 7 days.

Device IDs and User IDs minimum length

Device IDs and User IDs must be strings with a length of 5 characters or more. This is to prevent potential instrumentation issues. If an event contains a device ID or user ID that's too short, the ID value is removed from the event.

Override the default minimum length of 5 characters by passing the min_id_length option with the request.

If the event doesn't have a user_id or device_id value, Amplitude can reject the with a 400 status.

Language field

If the language field in the request contains a tag, the tag changes to its human-friendly language name. For example, if a request contains "language": "en-US", it changes to "language": "English" before Amplitude stores it.

The following table shows the list of mappings. Language tags are case-insensitive.

Request

POST https://api2.amplitude.com/2/httpapi

Headers

To send data to Amplitude HTTP V2 API, a Content-Type header must be set to application/json.

Body parameters

Event array keys

You can send these keys in the JSON event object. One of user_id or device_id is required, as well as the event_type.

Options

Response

Amplitude recommends that you implement retry logic and send an insert_id (used for deduplication of the same event) in your events. This prevents lost events or duplicated events if the API is unavailable or a request fails.

200

200 OK: Successful real time event upload. If you don't receive a 200 OK response, retry your request.

{
  "code": 200,
  "events_ingested": 50,
  "payload_size_bytes": 50,
  "server_upload_time": 1396381378123
}

400

400 Bad Request. A 400 indicates invalid upload request. Check the response for more information.

Possible reasons for an invalid request:

• The request body isn't valid JSON. The error returned is "Invalid JSON request body".
• The request body is missing required fields. The error returned is "Request missing required field", and indicates which fields are missing.
• The events object has invalid fields. events_with_invalid_fields maps field names to the index of the first event that returns an error.
• Some devices are silenced.

Properties (invalid or missing JSON)

Properties (SilencedDeviceID)

403 (forbidden)

403 Forbidden. The request is blocked by Amplitude's Web Application Firewall (WAF).

Possible reasons for the response:

• The request contains invalid values within the Header, Body, and/or URI that match our security filters
• The request is from a sanctioned region from which Amplitude isn't allowed to accept requests.

{
  "code": 403,
  "error": "Forbidden"
}

Properties

413 (payload too large)

413 Payload Too Large. The payload size is too big (request size exceeds 1MB). Split your events array payload into multiple requests and try again.

{
  "code": 413,
  "error": "Payload too large"
}

Properties

429 (too many requests)

429 Too Many Requests. Too many requests for a user or device. Amplitude throttles requests for users and devices that exceed 30 events per second (measured as an average over a recent time window). You should pause sending events for that user or device for a period of 30 seconds before retrying and continue retrying until you no longer receive a 429 response.

{
  "code": 429,
  "error": "Too many requests for some devices and users",
  "eps_threshold": 30,
  "throttled_devices": {
    "C8F9E604-F01A-4BD9-95C6-8E5357DF265D": 31
  },
  "throttled_users": {
    "datamonster@amplitude.com": 32
  },
  "throttled_events": [
    3,
    4,
    7
  ]
}

Properties

Server Error 500, 502, 504

500, 502, and 504 Server Error. Amplitude encountered an error while handling the request. A request with this response may not have been accepted by Amplitude. If you retry the request, it could duplicate the events. To avoid duplication, send an insert_id in your requests.

503 Service Unavailable

503 Service Unavailable. Request failed because of an internal Amplitude issue. Retrying a request with a 503 response doesn't risk duplicating events.