The Amp Devcenter Test Developer Hub

Welcome to the Amp Devcenter Test developer hub. You'll find comprehensive guides and documentation to help you start working with Amp Devcenter Test as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

HTTP API (Deprecated)

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.

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 Enterprise plan. 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.

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 below.

Request Format

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

Required ArgumentDescription
api_keyAPI key which can be found in your project's Settings page. 040062a5d38552315b98302ba4f2f
eventEither 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.

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.
  • 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.

Example Requests

Sending a POST event call request:

curl --data 'api_key={API_KEY}' --data-urlencode 'event=[{"user_id":"[email protected]",
    "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 Identify call request:
curl --data 'api_key={API_KEY}' --data-urlencode 'event=[{"user_id":"[email protected]",
    "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%22 user_id%22%3A%22datamonster%40gmail.com%22%2C%20%22event_type%22%3A%22 watch_tutorial%22%2C%20%22user_properties%22%3A%7B%22Cohort%22%3A%22 Test%20A%22%7D%2C%20%22country%22%3A%22United%20States%22%2C%20%22 ip%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.

IMPORTANT NOTE: This should not be used if device_brand, device_manufacturer, and device_model are used.

KeyDescription
user_id (string)(required unless device_id is present) A readable ID specified by you. "[email protected]"
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. It will be set to the 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. Object depth may not exceed 40 layers. 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. Object depth may not exceed 40 layers. 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 groupType(s), while "1" and ["Amplitude", "DataMonster"] are groupName(s). 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 if revenue is not sent) 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)revenue = price quantity If you send all three fields of price, quantity, and revenue, then (price quantity) will take precedence and be the revenue value. You can use negative values to indicate refunds. 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). AEBE52E7-03EE-455A-B3C4-E57283966239
android_id (string)(Android) Android ID (not the advertising ID). BCCE52E7-03EE-321A-B3D4-E57123966239

Footnotes

  1. 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.

  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 KeyDescription
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 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

Common Issues with HTTP API Implementations

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.

Product Analytics Considerations

It is important to make sure that everything you want to log is represented in your server API. For example, in a funnel, you may only send a single call to the server at the end, but you might want to track the user as they progress through the steps.

Also, there is context that might not be tracked on the server. An example is the location where an action was performed (if there is more than one way to perform an action), which might not be passed to the server.

To make sure that everything required is available server-side, you can start by writing out 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 some 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 aren't sent successfully

Make sure to familiarize yourself with our HTTP response codes, and that your server handles them correctly.

Also make sure you are familiar with our insert_id, which allow us to deduplicate events if you happen to send duplicate events.

Finally, the session_id has to be in a specific format (ms since the epoch) for us to track them properly. Both session_id and insert_id are covered in the above section.

Updated 4 months ago


HTTP API (Deprecated)


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.