HTTP V2 API

Regions

The base URL depends on your project's data residency. In all examples on this page, use the default base URL unless your project uses Amplitude's EU data center—in that case use the EU base URL in this table.

This API uses the event ingestion host api2.amplitude.com (default) or api.eu.amplitude.com (EU). Other Amplitude APIs use different hostnames (for example api.amplitude.com, core.amplitude.com, data-api.amplitude.com, or experiment.amplitude.com). The https://analytics.amplitude.com hostname is the Analytics web app (browser UI), not an ingestion endpoint.

Considerations

Note the following 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 sending no 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. If you exceed these size limits, you get a 413 error.

If you have high volume and need to scale, partition your work based on device_id or user_id. Partitioning ensures that throttling on a particular device_id or user_id doesn't affect all senders in your system. If you use a proxy service to send events to Amplitude, make sure that throttling forwards to your clients, so that spammy clients don't slow down a partition of work in your system.

Information for partner integrations

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

To find your integration's partner ID and a payload example, refer to 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 pass the IDFA as the device ID, first check the IDFA value. If the IDFA is all zeros, pass a different value for the device ID, such as the Identifier for Vendor (IDFV).

Windows OS

If you use a Windows operating system, you may need 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 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

Send the time parameter in each event as milliseconds since epoch. Any other format (such as ISO format) results in a 400 Bad Request response.

Event deduplication

Amplitude strongly recommends that you send an insert_id for each event to prevent sending duplicate events. 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 of 5 characters or more. The minimum length prevents potential instrumentation issues. If an event contains a device ID or user ID that's too short, Amplitude removes the ID value 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 event with a 400 status.

Language field

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

Language tags are case-insensitive.

Request

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

Headers

To send data to the Amplitude HTTP V2 API, set the Content-Type header 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, and the event_type is required.

Options

Response

Amplitude recommends that you implement retry logic and send an insert_id (used to deduplicate the same event) in your events. Retry logic and insert_id prevent lost 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 an 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. Amplitude's Web Application Firewall (WAF) blocked the request.

Possible reasons for the response:

• The request contains invalid values within the Header, Body, or URI that match Amplitude 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 1 MB). 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. Pause sending events for that user or device for 30 seconds, then retry. 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. Amplitude may not have accepted a request with this response. If you retry the request, the retry could duplicate the events. To avoid duplication, send an insert_id in your requests.

503 Service Unavailable

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