HTTP API

Use the HTTP API to send data directly from your server to our endpoint. In the examples below the parameters are highlighted purple, and the values in red are what you need to replace with the parameters you are specifically interested in.

Table of Contents

• Important Notes
• Upload Limit
• All Zero Device IDs: Limited Ad Tracking Enabled
• HTTP Status Codes & Retrying Failed Requests
• Windows Operating System
• String Character Limit
• Setting Date Values
• Event Deduplication
• Request Format
• Example Requests
• Keys for the Event Argument
• Footnotes
• Optional Keys

Important Notes 

Upload Limit 

Limit your upload to 100 batches/sec and 1000 events/sec. You can batch events into an upload but we recommend not sending more than 10 events per batch. Thus, we expect at most 100 batches to be sent per second, and so the 1000 events/sec limit still applies as we do not recommend sending more than 10 events per batch. Note: This applies to customers on our Starter Plan only. 

For paying customers, please reach out to us if you need to send more than 1000 events/sec. There is no hard limit on the Amplitude Growth and Enterprise plans. However, please note that we will throttle requests for individual devices that exceed 10 events/second as stated in the below HTTP status codes section.

For request size, please limit your requests to no more than 2000 events per request and under 1 MB. If you exceed these size limits, you will receive a 413 error.

Recommendation: For high volume customers concerned with scale, please partition your work based on device_id (or user_id if you don't have a device_id). This ensures that throttling on a particular device_id (or user_id) doesn't impact all senders in your system. If you are proxying events to Amplitude, please ensure that throttling is forwarded to your clients to create backpressure instead of letting spammy clients slow down a partition of work in your system.

All Zero Device IDs: Limited Ad Tracking Enabled

As of iOS 10, if the user enables Limit Ad Tracking, Apple will replace the Identifier for Advertiser (IDFA) with all zeros. Amplitude will drop a Device ID of all zeros from the event and return an error on the request (since Device IDs are required for all events). Thus, if you are passing the IDFA as the Device ID, then we recommend running a check on the IDFA value and passing a different Device ID value like the Identifier for Vendor (IDFV) instead.

HTTP Status Codes & Retrying Failed Requests

It's important that you implement retry logic and send an insert_id, in the unlikely event that our API endpoint becomes unavailable and we are unable to ingest events. If you do not receive a 200 status code (which means your event was successfully received by Amplitude), then you should retry your request. Here are the other HTTP status codes you may receive:

• 400: Your request is malformed.
  • In rare situations, the body will be "silenced". This means that requests for a specific device_id value has been permanently silenced and rejected because our servers have identified data from that device_id to be likely spam and from bots.
• 413: You had too many events in your request.
• Customers should keep their payload size well under 1MB. If you are worried about receiving 413 errors, then you should have logic which halves your payloads repeatedly until payloads start going through.
• You will also receive this error if you exceed more than 2000 events per request.
• 429: Too many requests for a device.
• Amplitude will throttle requests for devices (device_ids) that exceed 10 events per second (measured as an average over a recent time window). When we throttle a request, the response will have HTTP status code 429 and the body will be "too_many_requests_for_device". You should pause sending events for any devices in that request for a period of 30 seconds before retrying and then continue retrying until you no longer receive status code 429.
• Amplitude will also throttle requests for users (user_ids) that exceed this limit. If the same User ID is sending events from multiple devices simultaneously, then all of those devices would be throttled.
• Recommendation: For high volume customers concerned with scale, please partition your work based on device_id (or user_id if you don't have a device_id). This ensures that throttling on a particular device_id (or user_id) doesn't impact all senders in your system. If you are proxying events to Amplitude, please ensure that throttling is forwarded to your clients to create backpressure instead of letting spammy clients slow down a partition of work in your system.

• 500, 502, & 504: We encountered an error while handling the request.
• A request with this response may or may not have been accepted by Amplitude, upon retrying the request, the events may or may not be duplicated. To resolve this risk, we recommend sending an insert_id in your requests.
• 503: Server error.
• If we do not commit your request to our system as a result of an internal failure, then we will return HTTP status code 503. A request with this response can be retried without any risk of duplicating an event.
• Client-side Timeouts:
• Read your HTTP request library's documents to learn the best way to manage and handle client-side timeouts.

Windows Operating System

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

String Character Limit

There is a character limit of 1024 characters for all string values (user_id, event or user property values, etc.).

Setting Date Values

Amplitude compares dates as strings, so it is recommended to use the ISO 8601 format (YYYY-MM-DDTHH:mm:ss), which will allow you to perform date comparisons in the platform, (e.g. '2016-01-31' > '2016-01-01'). This will also work for datetime values (e.g. '2017-08-07T10:09:08' > '2017-08-07T01:07:00').

Event Deduplication

It is highly recommended that you send an insert_id for each event to prevent duplicate events from being received by Amplitude. We will ignore subsequent events sent with the same insert_id within the past 7 days. You can read more about this field here.

Request Format

Send a POST or GET request to https://api.amplitude.com/httpapi with two request parameters:

IMPORTANT NOTE: Special characters need to be URL encoded. For example, if your event is named "event name", it needs to be formatted as "event20%name" in your request.

Example Requests

Sending a POST event call request:

curl --data 'api_key=API_Key' --data-urlencode 'event=[{"user_id":"12345", "event_type":"watch_tutorial", "user_properties":{"Cohort":"Test A"}, "country":"United States", "ip":"127.0.0.1", "time":1396381378123}]' https://api.amplitude.com/httpapi

Sending a POST event call request (to log Revenue event):

curl --data 'api_key=API_Key' --data-urlencode 'event=[{"user_id":"12345", "event_type":"buy_song", "productId":4, "quantity":1, "price":630, "revenueType": "income", "paying": "true", "user_properties":{"order_status":"new_arrival"}}]' https://api.amplitude.com/httpapi

Sending a POST Identify call request:

curl --data 'api_key=API_Key' --data-urlencode 'event=[{"user_id":"12345", "event_type":"$identify", "user_properties":{"$set": {"Cohort":"Test B"}, "$add": {"friendCount":3}}, "country":"United States", "ip":"127.0.0.1", "time":1396381378123}]' https://api.amplitude.com/httpapi

Sending a GET event call request:

curl -v 'https://api.amplitude.com/httpapi?api_key=API_Key&event=%5B%7B%22user_id%22%3A%2212345%22%2C%20%22event_type%22%3A%22watch_tutorial%22%2C%20%22user_properties%22%3A%7B%22Cohort%22%3A%22Test%20A%22%7D%2C%20%22country%22%3A%22United%20States%22%2C%20%22ip%22%3A%22127.0.0.1%22%2C%20%22time%22%3A1396381378123%7D%5D'

Note that in this GET request, the body of the event (same as the one from the POST request) is URL encoded.

Keys for the Event Argument

The following keys can be sent within the JSON event object. Note that one of user_id or device_id is required, as well as the event_type.

Note: '[Amplitude] Country', '[Amplitude] City', '[Amplitude] Region', and '[Amplitude] DMA' are user properties pulled using GeoIP. For any HTTP API events, if GeoIP information is unavailable, then we pull the information from the 'location_lat' and 'location_lng' keys if those keys are populated. If these location properties are manually set, then Amplitude will not modify that property.

"event_type":"$identify"

Footnotes

¹These user properties and all other user properties persist in following events if not explicitly changed at the time of subsequent events (as of 06/24/2016). Please refer to footnotes 2 and 3 to assure that you update these properties appropriately.

² These fields (platform, os_name, os_version, device_brand, device_manufacturer, device_model, and carrier) must all be updated together. Setting any of these fields will automatically reset all of the other property values to null if they are not also explicitly set for the same event. All property values will otherwise persist to a subsequent event if the values are not changed to a different string or if all values are passed as null. Amplitude will attempt to use device_brand, device_manufacturer, and device_model to map the corresponding device type.

³ These fields (country, region, city, DMA) must all be updated together. Setting any of these fields will automatically reset all of the other property values to null if they are not also explicitly set for the same event. All property values will otherwise persist to a subsequent event if the values are not changed to a different string or if all values are passed as null.

⁴ To implement property values as arrays, restructure the key-value pairs as follows: "property_name": [value1, value2, value3]. Note: For all event/user properties that Amplitude automatically tracks, you cannot store their values as an array. For example, you cannot store the values of '[Amplitude] Country' as an array.

⁵ If this field is populated with a non-zero value, then the event is assumed to be a revenue event.

Optional Keys

The following optional keys are interpreted in a special way on our backend.