Batch Event Upload API

The Batch Event Upload API lets you upload large amounts of event data.

The event JSON format follows the HTTP API format, and has the same requirements.

Authentication

This API uses your API key passed in the body of the request:

api-key=API_KEY

For more information, see Find your API Credentials

Endpoints

Region Endpoint
Standard server https://api2.amplitude.com/batch
EU residency server https://api.eu.amplitude.com/batch

Considerations

  • The JSON serialized payload must not exceed 20MB in size.
  • To prevent instrumentation issues, device IDs and user IDs must be strings with a length of 5 characters or more. If an event has a device or user ID that's too short, the ID value is dropped from the event. If an event doesn't have a user or device ID, it may cause the API to reject the upload with a 400 error. You can change the minimum ID length using the options property.
  • Each API key can send up to 1000 events per second for any individual device ID or user ID. If you exceed that rate, the API rejects the upload, and gives a 429 response. Check the response summary for more information.

Use this request to bulk upload events to Amplitude.

Request

The Batch Event Upload API has two differences in the request as compared to the HTTP API:

  • Content-type must be application/json.
  • The key for the events payload is events plural, not event singular.

1# You can also use wget
2curl -X POST https://api2.amplitude.com/batch \
3 -H 'Content-Type: application/json' \
4 -H 'Accept: */*'

1POST https//api2.amplitude.com/batch HTTP/1.1
2Host: api2.amplitude.com
3Content-Type: application/json
4Accept: */*

Body

Parameter Description
body Required. UploadRequestBody. A JSON object that contains your API key and an array of events.

These properties belong to the request's body.

Name Description
api_key Required. String. Amplitude project API key
events Required. Array of events to upload
options Optional. Options for the request.
1{
2 "api_key": "my_amplitude_api_key",
3 "events": [
4 {
5 "user_id": "datamonster@gmail.com",
6 "device_id": "C8F9E604-F01A-4BD9-95C6-8E5357DF265D",
7 "event_type": "watch_tutorial",
8 "time": 1396381378123,
9 "event_properties": {
10 "load_time": 0.8371,
11 "source": "notification",
12 "dates": [
13 "monday",
14 "tuesday"
15 ]
16 },
17 "user_properties": {
18 "age": 25,
19 "gender": "female",
20 "interests": [
21 "chess",
22 "football",
23 "music"
24 ]
25 },
26 "groups": {
27 "team_id": "1",
28 "company_name": [
29 "Amplitude",
30 "DataMonster"
31 ]
32 },
33 "app_version": "2.1.3", ...
34 "platform": "iOS",
35 "os_name": "Android",
36 "os_version": "4.2.2",
37 "device_brand": "Verizon",
38 "device_manufacturer": "Apple",
39 "device_model": "iPhone 9,1",
40 "carrier": "Verizon",
41 "country": "United States",
42 "region": "California",
43 "city": "San Francisco",
44 "dma": "San Francisco-Oakland-San Jose, CA",
45 "language": "English",
46 "price": 4.99,
47 "quantity": 3,
48 "revenue": -1.99,
49 "productId": "Google Pay Store Product Id",
50 "revenueType": "Refund",
51 "location_lat": 37.77,
52 "location_lng": -122.39,
53 "ip": "127.0.0.1",
54 "idfa": "AEBE52E7-03EE-455A-B3C4-E57283966239",
55 "idfv": "BCCE52E7-03EE-321A-B3D4-E57123966239",
56 "adid": "AEBE52E7-03EE-455A-B3C4-E57283966239",
57 "android_id": "BCCE52E7-03EE-321A-B3D4-E57123966239",
58 "event_id": 23,
59 "session_id": 1396381378123,
60 "insert_id": "5f0adeff-6668-4427-8d02-57d803a2b841"
61 }
62 ]
63}

Event

These properties belong to the events object.

Name
Description
user_id Required. String. A readable ID specified by you. Must have a minimum length of 5 characters.
Required unless device_id is present.
device_id Required. String. A device-specific identifier, such as the Identifier for Vendor on iOS. Required unless user_id is present. If a device_id isn't sent with the event, it's set to a hashed version of the user_id.
event_type Required. String. A unique identifier for your event.
Note: $identify and $groupidentify are predefined for identification and group identification. More information about the two operations is in the description of "user_properties" and "group_properties".
time Optional. Long. The timestamp of the event in milliseconds since epoch. If time isn't sent with the event, it's set to the request upload time.
event_properties Optional. Object. A dictionary of key-value pairs that represent properties sent along with the event. You can store property values in an array. Date values are transformed into string values. Object depth may not exceed 40 layers.
user_properties Optional. Object. A dictionary of key-value pairs that represent data tied to the user. You can store property values in an array. Date values are transformed into string values. User property operations ($set, $setOnce, $add, $append, $unset) are supported when event_type is $identify. Object depth may not exceed 40 layers.
groups Optional. Object. This feature is available only to 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. Note: You can only track up to 5 unique group types and 10 total groups. Any groups past that threshold aren't tracked.
group_properties Optional. Object. This feature is available only to customers who have purchased the Accounts add-on. When "event_type" is $groupidentify, the field is a dictionary of key-value pairs that represent properties tied to the groups listed in the "groups" field. The field is ignored for other event types. Group property operations ($set, $setOnce, $add, $append, $unset) are also supported.
$skip_user_properties_sync Optional. Boolean. When true user properties aren't synced. Defaults to false.
app_version Optional. String. The current version of your application.
platform Optional. String. Platform of the device.
os_name Optional. String. The name of the mobile operating system or browser that the user is using.
os_version Optional. String. The version of the mobile operating system or browser the user is using.
device_brand Optional. String. The device brand that the user is using.
device_manufacturer Optional. String. The device manufacturer that the user is using.
device_model Optional. String. The device model that the user is using.
carrier Optional. String. The carrier that the user is using.
country Optional. String. The current country of the user.
region Optional. String. The current region of the user.
city Optional. String. The current city of the user.
dma Optional. String. The current Designated Market Area of the user.
language Optional. String. The language set by the user.
price Optional. Float. The price of the item purchased. Required for revenue data if the revenue field isn't sent. You can use negative values for refunds.
quantity Optional. Integer. The quantity of the item purchased. Defaults to 1 if not specified.
revenue Optional. Float. Revenue = (price * quantity). If you send all 3 fields of price, quantity, and revenue, then (price * quantity) is used as the revenue value. You can use negative values to identify refunds.
productId Optional. String. An identifier for the item purchased. You must send a price and quantity or revenue with this field.
revenueType Optional. String. The type of revenue for the item purchased. You must send a price and quantity or revenue with this field.
location_lat Optional. Float. The current Latitude of the user.
location_lng Optional. Float. The current Longitude of the user.
ip Optional. String. The IP address of the user. Use "$remote" to use the IP address on the upload request. Amplitude uses the IP address to reverse lookup a user's location (city, country, region, and DMA). Amplitude can drop the location and IP address from events once it reaches Amplitude servers. You can submit a request to Amplitude Support to configure this for you.
idfa Optional. String. (iOS) Identifier for Advertiser.
idfv Optional. String. (iOS) Identifier for Vendor.
adid Optional. String. (Android) Google Play Services advertising ID
android_id Optional. String. (Android) Android ID (not the advertising ID)
event_id Optional. Integer. An incrementing counter to distinguish events with the same user_id and timestamp from each other. Amplitude recommends that you send an event_id, increasing over time, especially if you expect events to occur simultaneously.
session_id Optional. Long. The start time of the session in milliseconds since epoch (Unix Timestamp), necessary if you want to associate events with a particular system. A session_id of -1 is the same as no session_id specified.
insert_id Optional. String. A unique identifier for the event. Amplitude deduplicates subsequent events sent with an insert_id that has been seen within the past 7 days. Amplitude recommends generating a UUID or using some combination of device_id, user_id, event_type, event_id, and time.
plan Optional. Object. Tracking plan properties. Amplitude accepts only branch, source, version properties.
plan.branch Optional. String. The tracking plan branch name. For example: "main"
plan.source Optional. String. The tracking plan source. For example: "web"
plan.version Optional. String. The tracking plan version. For example: "1", "15"

Options

These properties belong to the options object.

Name
Description
min_id_length Optional. Integer. Sets the minimum permitted length for user_id and device_id fields. Default is five.

Responses

Status Meaning Description
200 OK Successful batch upload.
400 Bad Request Invalid upload request. Read the error message to fix the request.
413 Payload Too Large Payload size is too big (request size exceeds 20MB). Split your events array payload in half and try again. The limit per batch is 2000 events.
429 Too Many Requests Too many requests for a user or device. Amplitude throttles requests for users and devices that exceed 1000 events per second or 500,000 events per day.

SuccessSummary

1{
2 "code": 200,
3 "events_ingested": 50,
4 "payload_size_bytes": 50,
5 "server_upload_time": 1396381378123
6}
Name
Description
code Integer. 200 success code
events_ingested Integer. The number of events ingested from the upload request.
payload_size_bytes Integer. The size of the upload request payload in bytes.
server_upload_time Integer. The time in milliseconds since epoch (Unix Timestamp) that Amplitude's event servers accepted the upload request.

InvalidRequestError

1{
2 "code": 400,
3 "error": "Request missing required field",
4 "missing_field": "api_key",
5 "events_with_invalid_fields": {
6 "time": [
7 3,
8 4,
9 7
10 ]
11 },
12 "events_with_missing_fields": {
13 "event_type": [
14 3,
15 4,
16 7
17 ]
18 }
19}
Name
Description
code 400 error code.
error String. Error description
missing_field String. Indicates which request-level required field is missing.
events_with_invalid_fields Object. A map from field names to an array of indexes into the events array indicating which events have invalid values for those fields
events_with_missing_fields Object. A map from field names to an array of indexes into the events array indicating which events are missing those required fields

SilencedDeviceID

1{
2 "code": 400,
3 "eps_threshold": 100,
4 "error": "Events silenced for device_id",
5 "exceeded_daily_quota_devices":
6 {},
7 "silenced_devices":
8 [
9 "silenced_device_id_1",
10 "silenced_device_id_2"
11 ],
12 "silenced_events":
13 [
14 5,
15 6
16 ],
17 "throttled_devices":
18 {
19 "throttled_device_id_1": 0,
20 "throttled_device_id_2": 100
21 },
22 "throttled_events":
23 [
24 3,
25 4
26 ]
27}
Name
Description
code 400 error code
error String. Error description.
eps_threshold Integer. Your app's current events per second threshold. If you exceed this rate your requests will be throttled.
exceeded_daily_quota_devices Integer. A map from device_id to its current number of daily events, for all devices that exceed the app's daily event quota.
silenced_devices [string]. Array of device_ids that have been silenced by Amplitude.
silenced_events [integer]. Array of indexes in the events array indicating events whose device_id got silenced.
throttled_devices Object. A map from device_id to its current events per second rate, for all devices that exceed the app's current threshold.
throttled_events [integer]. Array of indexes in the events array indicating events whose user_id and/or device_id got throttled

PayloadTooLargeError

1{
2 "code": 413,
3 "error": "Payload too large"
4}
Name Description
code Integer. 413 error code
error String. Error description.

TooManyRequestsForDeviceError

1{
2 "code": 429,
3 "error": "Too many requests for some devices and users",
4 "eps_threshold": 1000,
5 "throttled_devices": {
6 "C8F9E604-F01A-4BD9-95C6-8E5357DF265D": 4000
7 },
8 "throttled_users": {
9 "datamonster@amplitude.com": 4000
10 },
11 "exceeded_daily_quota_users": {
12 "datanom@amplitude.com": 500200
13 },
14 "exceeded_daily_quota_devices": {
15 "A1A1A000-F01A-4BD9-95C6-8E5357DF265D": 500900
16 },
17 "throttled_events": [
18 3,
19 4,
20 7
21 ]
22}
Name
Description
code Integer. 429 error code
error String. Error description.
eps_threshold Integer. Your app's current events per second threshold. If you exceed this rate your requests are throttled.
throttled_devices Object. A map from device_id to its current events per second rate, for all devices that exceed the app's current threshold.
throttled_users Object. A map from user_id to their current events per second rate, for all users that exceed the app's current threshold
throttled_events [integer]. Array of indexes in the events array indicating events whose user_id or device_id got throttled

Code 429 explained

Amplitude rejects a request with a 429 status, it means that a device or user in that request was throttled. The error response has the details, so logging the response lets you investigate which users or devices were the cause of throttling.

Because device_id and user_id are the attributes that trigger throttling, partitioning work on one of these attributes helps isolate throttling to a specific partition of work. This way partitions which aren't being throttled can still make progress.

EPDS and EPUS

Amplitude measures the rate of events for each deviceID and each userID for a project. Amplitude calls these rates events per device second (EPDS) and events per user second (EPUS), respectively. These values are both averaged over a period of 30 seconds.

Example

To reach an EPDS limit of 1000, a device must send 30,000 events in a 30-second period. This causes the device to be throttled and responds with a HTTP status 429.

In general, your app shouldn't measure EPDS or EPUS itself. Send requests to Amplitude as fast as possible. When you receive a 429, wait for a short period (for example, 15 seconds) before trying to send that request again.

Daily limit

In addition to the per-second limit, there is daily limit to prevent against spam and abuse. This limit is hard to exceed. Events starts counting toward the daily limit after Amplitude determines that a user/device is spamming the system. After a project reaches the limit, Amplitude enforces a daily limit of 500,000 events uploaded per rolling 24 hours. The 24 hour rolling period applies in one-hour intervals. The daily limit applies for each deviceID and each user_id for a project.

The daily limit is independent of the EPDS/EPUS. After a user or device has hit the 500,000 event daily limit for a particular project, Amplitude rejects batches that contain the user or device ID. In those cases, the request returns a 429 response with a body indicating "exceeded_daily_quota_users" or "exceeded_daily_quota_devices" with list of deviceIDs and userIDs. Retry the batch when there are less than 500,000 events uploaded for a user or device in the previous 24 hour period.

Was this page helpful?

Thanks for your feedback!

May 21st, 2024

Need help? Contact Support

Visit Amplitude.com

Have a look at the Amplitude Blog

Learn more at Amplitude Academy

© 2024 Amplitude, Inc. All rights reserved. Amplitude is a registered trademark of Amplitude, Inc.