Important Note:
- This API is now deprecated. Please use HTTP API V2 instead.
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
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 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_id
s) 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_id
s) 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) for event/user properties only, 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').
For 'time', which is used to set the time of the event, it must be in epoch time (e.g. "time":1396381378123).
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 to the same project 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:
Required Argument | Description |
---|---|
api_key | API key which can be found in your project's Settings page.
"040062a5d38552315b98302ba4f2f" |
event | Either a single JSON event object (see below for fields) or an array of JSON objects, each of which represents one event.
See below for examples. |
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.
Key | Description |
---|---|
user_id
string |
(required unless device_id is present) A readable ID specified by you.
"12345" |
device_id
string |
(required unless user_id is present) A device specific identifier, such as the Identifier for Vendor on iOS.
"C8F9E604-F01A-4BD9-95C6-8E5357DF265D" Note: If a Device ID is not sent with the event, Device ID will be set to a hashed version of that user's User ID. |
event_type
string |
(required) A unique identifier for your event. IMPORTANT NOTE: The following event names are reserved for Amplitude use: "[Amplitude] Start Session", "[Amplitude] End Session", "[Amplitude] Revenue", "[Amplitude] Revenue (Verified)", "[Amplitude] Revenue (Unverified)", and "[Amplitude] Merged User". You should not send server-side events with these same names. "watch_tutorial" |
time
long |
The timestamp of the event in milliseconds since epoch. This will update the client event time. If not specified, this value will assume the server upload time by default.
1396381378123 |
event_properties4
dictionary |
A dictionary of key-value pairs that represent additional data to be sent along with the event. Note: You can store property values in an array, and date values are transformed into string values. {"load_time": 0.8371, "source": "notification", "dates": ["monday", "tuesday"]} |
user_properties4
dictionary |
A dictionary of key-value pairs that represent additional data tied to the user. Each distinct value will show up as a user segment on the Amplitude dashboard.
Note: You can store property values in an array, and date values are transformed into string values. {"age": 25, "gender": "female", "interests": ["chess", "football", "music"]} In addition, user property operations ($set, $setOnce, $add, $append, $unset) are only supported with an Identify call within the HTTP API; please set: "event_type":"$identify" Similar to calls via Identify API, user property values updated by an Identified call will not reflect on any Amplitude charts until the user's following event. And you cannot mix user property operations with actual top-level user properties; instead, include them inside the "$set" operation. If you are using one of these operators then this dictionary can only contain user property operations and cannot be combined with the above format e.g. you cannot do {"$append":{"interests":"Music"}, "subscription type":"paid"} in the same request. {"$set": {"cohort": "Test A"}, "$setOnce": {"startDate": "2015-10-01"}, "$add": {"friendCount": 3}, "$append": {"interests": "Music"}, "$prepend":{"sports": "Tennis"}, "$unset": {"oldProperty": "-"}} |
groups4
dictionary |
(Enterprise only) This feature is only available to Enterprise customers who have purchased the Accounts add-on. This field adds a dictionary of key-value pairs that represent groups of users to the event as an event-level group. See this excerpt in our Javascript SDK for more information on groups. Instrumenting groups will allow you to utilize our account-level reporting. In the example below, "company_id" and "company_name" are Note: You can only track up to 5 groups. Any groups pass that threshold will not be tracked. This field also sets an event-level group, meaning the group designation only applies for the specific event being logged and does not persist on the user unless you explicitly set it through Amplitude's SDKs or through the Identify API. {"company_id": "1", "company_name":["Amplitude", "DataMonster"]} |
app_version
string |
The version of your application the user is on.
"2.1.3" |
platform1, 2
string |
Platform of the device.
"iOS", "Android", or "Web" |
os_name1, 2
string |
The mobile operating system or browser the user is on.
"iOS", "Android", "Chrome" |
os_version1, 2
string |
The version of the mobile operating system or browser the user is on.
"8.1", "4.2.2", "37" |
device_brand1, 2
string |
The device brand the user is on.
"Verizon" |
device_manufacturer1, 2
string |
The device manufacturer the user is on.
"Samsung", "Asus", "Apple" |
device_model1, 2
string |
The device model the user is on.
"Mac", "iphone 9,1", "sm-g30f" |
carrier1, 2
string |
Carrier of the device.
"Verizon" |
country1, 3
string |
The country the user is in.
"United States" |
region1, 3
string |
The geographical region the user is in.
"California" |
city1, 3
string |
What city the user is in.
"San Francisco" |
dma1, 3
string |
The Designated Market Area of the user.
"San Francisco-Oakland-San Jose, CA" |
language1
string |
What language the user has set.
"English" |
price5
float |
(required for revenue data) The price of the item purchased. You can use negative values to indicate refunds.
4.99, -1.99 |
quantity5
integer |
(required for revenue data, defaults to 1 if not specified) The quantity of the item purchased.
1, 2 |
revenue5
float |
(required for revenue data, needs to be the total of price*quantity) revenue = price * quantity 4.99, -1.99 |
productId5
string |
An identifier for the product. Note: You must send a price and quantity with this field. "Google Play Store Product Id", "Medium Bundle" |
revenueType5
string |
Type of revenue. Note: You must send a price and quantity with this field. "tax", "refund" |
location_lat
float |
Latitude of the user.
37.77 |
location_lng
float |
Longitude of the user.
-122.39 |
ip1
string |
IP address of the user. Use "$remote" to use your server's IP address. We will then use the collected IP address to reverse lookup a user's location user properties (City, Country, Region, and DMA). However, Amplitude has the ability to drop this data once it reaches our servers. If you'd like to drop IP address, Latitude and Longitude, or City and DMA information from your data, please submit a request to our team of Platform Specialists here and they can configure this for you.
"127.0.0.1" |
idfa
string |
(iOS) Identifier for Advertiser.
"AEBE52E7-03EE-455A-B3C4-E57283966239" |
idfv
string |
(iOS) Identifier for Vendor.
"BCCE52E7-03EE-321A-B3D4-E57123966239" |
adid
string |
(Android) Google Play Services advertising ID (AdID). For Amazon devices, set this to the Amazon Advertising ID.
"AEBE52E7-03EE-455A-B3C4-E57283966239" |
android_id
string |
(Android) Android ID (not the advertising ID).
"BCCE52E7-03EE-321A-B3D4-E57123966239" |
Footnotes
1These 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.
2 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.
3 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.
4 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.
5 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.
Optional Amplitude Specific Key | Description |
---|---|
event_id
int |
An incrementing counter to distinguish events with the same user_id and timestamp from each other. Note: We recommend you send an event_id, increasing over time, especially if you suspect any events to occur simultaneously. An event_id is not required to send a session_id though. 1 |
session_id
long |
The start time of the session in milliseconds since epoch (Unix Timestamp), necessary if you want to associate events with a particular session (a session_id of -1 implies that you not sending a session_id, and so no session metrics will be tracked). Here is more information. 1396381378123 |
insert_id
string |
A unique identifier for the event being inserted; we will deduplicate subsequent events sent to the same project with an insert_id we have already seen before within the past 7 days. Some combination of device_id, user_id, session_id, event_type, and event_id or time, would likely serve as a sufficient insert_id value. "f47ac10b-58cc-4372-a567-0e02b2c3d479" |
Considerations for Developers
There are some considerations related to using the HTTP API rather than using our client libraries. Some of these relate to product analytics, and some are primarily technical. Please feel free to check out the Amplitude Developer centre for more details.
- Product analytics considerations: It is important to make sure that everything you want to log is represented in your Server API. Also, there is context that might not be tracked on the server such as the location where an action was performed, which might not be passed to the server. To make sure that everything required is available server-side, you can start by writing the flows you want to track and making sure that all of the events and event properties are represented by API calls.
- Technical considerations: There are a couple of things that the client SDKs take care of that you have to handle by yourself if you do the tracking server-side. The main things are session ids, insert ids and retry/connection logic. Amplitude's data collection endpoints have extremely high uptime, but there are very occasionally small outages, or you could hit the rate limits if you're sending a lot of data from your server. As a result, it's important that your retry logic is correct if you want to make sure that everything is logged correctly. Our client libraries store up to 1000 events and will retry if the events are not sent successfully.