The Batch Event Upload endpoint accepts JSON requests that contain an API key and a list of events.

The event JSON format follows our HTTP API format, and has the same requirements (such as each event must have an event type, etc). After a request is accepted successfully, the events in the batch should be queryable within 15 minutes most of the time. The JSON serialized payload must not exceed 20MB in size.

NOTE: In addition, device IDs and user IDs must be strings with a length of 5 characters or more. This is to prevent potential instrumentation issues. If an event contains a device or user ID that is too short, the ID value will be removed from the event. This may cause the upload to be rejected with a 400 error if that event does not have a user ID or device ID value.

Each API key is allowed to send up to 1000 events per second for any individual device / user Id. If you exceed that rate your upload will be rejected with a response code of 429. The response summary will indicate which device / user Ids have exceeded the limit, what their current events per second rate is, along with some other useful information. See below for more details.

Endpoint

429s in depth

Partition work by device_id if throughput is degraded
by throttling
                                .-----------.    .--------.
                             .->|Partition 1|--->|Worker 1|---.
.--------.                   |  '-----------'    '--------'   |  .---------.
|        |  .--------------. |  .-----------.    .--------.   '->|         |
|All data|->|hash device_id|--->|Partition 2|--->|Worker 2|----->|Amplitude|
|        |  '--------------' |  '-----------'    '--------'   .->|         |
'--------'                   |  .-----------.    .--------.   |  '---------'
                             '->|Partition 3|--->|Worker 3|---'
                                '-----------'    '--------'

We measure the rate of events for each deviceid and _each userid for a project, we refer to these rates as _events per device second (EPDS) & events per user second (EPUS) respectively. These are both averaged over a time window of (currently) 30 seconds. So for example an EPDS limit of 1000 would require that a device sends 30,000 events in a 30 second window for that device to be throttled i.e. receive HTTP status 429.

In addition to the per second limit, we also have a very rarely exceeded daily limit to prevent against spam and abuse. The limit will start counting after we’ve determined that a user/device is spamming us. We enforce a daily limit of 500,000 events uploaded per rolling 24 hours. The 24 hour rolling window applies in 1 hour interval. The daily limit applies for each deviceid and _each user_id for a project. Please note that this limit is independent of the EPDS/EPUS. Once a user/device has hit the 500,000 daily limit for a particular project any batches uploaded that contain that user/device will be rejected and we will return a 429 response with body indicating “exceeded_daily_quota_users” or “exceeded_daily_quota_devices” with list of deviceId/userId. The limit is rolling so once there are less than 500,000 events uploaded for a user/device in a given project in the last 24 hour period the batch can be retried. Please contact us for further support if you are encountering the daily limit.

When a request is throttled it means that some device or user in that request was throttled. Details about which can be found in the error response data. Logging the response will allow you to investigate which users or devices were the cause of throttling.

In general your application should not measure EPDS or EPUS itself. Send requests to Amplitude as fast as possible, then when a 429 error is received, sleep for a short period of time (e.g. 15 seconds) before trying to send that request again.

Because device_id and user_id are the attributes that determine throttling, partitioning work on one of these attributes will help isolate throttling to a specific partition of work. This way partitions which are not being throttled can still make progress while the throttled partitions are blocked by throttling.

Why use this endpoint instead of the HTTP API?

Feature comparison between /httpapi, /2/httpapi & /batch

Like the HTTP API, the Batch Event Upload endpoint can be used to send data directly from your server. Unlike the HTTP API, this endpoint is recommended for Customers that want to send large batches of data at a time, for example through scheduled jobs, rather than in a continuous realtime stream. Due to the higher rate of data that is permitted to this endpoint, data sent to this endpoint may be delayed based on load.

See Amplitude Help Center for more support articles and documentation.

Terms of service
Email: Support
License: MIT License

Post Batch

Code samples

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

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

var headers = {
  'Content-Type':'application/json',
  'Accept':'*/*'

};

$.ajax({
  url: 'https://api2.amplitude.com/batch',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const request = require('node-fetch');
const inputBody = '{
  "api_key": "my_amplitude_api_key",
  "events": [
    {
      "user_id": "[email protected]",
      "device_id": "C8F9E604-F01A-4BD9-95C6-8E5357DF265D",
      "event_type": "watch_tutorial",
      "time": 1396381378123,
      "event_properties": {
        "load_time": 0.8371,
        "source": "notification",
        "dates": [
          "monday",
          "tuesday"
        ]
      },
      "user_properties": {
        "age": 25,
        "gender": "female",
        "interests": [
          "chess",
          "football",
          "music"
        ]
      },
      "groups": {
        "company_id": "1",
        "company_name": [
          "Amplitude",
          "DataMonster"
        ]
      },
      "app_version": "2.1.3",
      "platform": "iOS",
      "os_name": "Android",
      "os_version": "4.2.2",
      "device_brand": "Verizon",
      "device_manufacturer": "Apple",
      "device_model": "iPhone 9,1",
      "carrier": "Verizon",
      "country": "United States",
      "region": "California",
      "city": "San Francisco",
      "dma": "San Francisco-Oakland-San Jose, CA",
      "language": "English",
      "price": 4.99,
      "quantity": 3,
      "revenue": -1.99,
      "productId": "Google Pay Store Product Id",
      "revenueType": "Refund",
      "location_lat": 37.77,
      "location_lng": -122.39,
      "ip": "127.0.0.1",
      "idfa": "AEBE52E7-03EE-455A-B3C4-E57283966239",
      "idfv": "BCCE52E7-03EE-321A-B3D4-E57123966239",
      "adid": "AEBE52E7-03EE-455A-B3C4-E57283966239",
      "android_id": "BCCE52E7-03EE-321A-B3D4-E57123966239",
      "event_id": 23,
      "session_id": 1396381378123,
      "insert_id": "5f0adeff-6668-4427-8d02-57d803a2b841"
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'*/*'

};

fetch('https://api2.amplitude.com/batch',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => '*/*'
}

result = RestClient.post 'https://api2.amplitude.com/batch',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': '*/*'
}

r = requests.post('https://api2.amplitude.com/batch', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api2.amplitude.com/batch");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"*/*"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /batch
Bulk upload events

Bulk upload events to Amplitude via the batch event upload endpoint.

If you have used our HTTP API before, note that there are two minor but important differences in your POST request to /batch. First, your Content-type must be application/json. Second, your key for the events payload is events plural, NOT event singular. Take a look at the code sample to the right for more details.

Body parameter

{
  "api_key": "my_amplitude_api_key",
  "events": [
    {
      "user_id": "[email protected]",
      "device_id": "C8F9E604-F01A-4BD9-95C6-8E5357DF265D",
      "event_type": "watch_tutorial",
      "time": 1396381378123,
      "event_properties": {
        "load_time": 0.8371,
        "source": "notification",
        "dates": [
          "monday",
          "tuesday"
        ]
      },
      "user_properties": {
        "age": 25,
        "gender": "female",
        "interests": [
          "chess",
          "football",
          "music"
        ]
      },
      "groups": {
        "team_id": "1",
        "company_name": [
          "Amplitude",
          "DataMonster"
        ]
      },
      "app_version": "2.1.3",
      "platform": "iOS",
      "os_name": "Android",
      "os_version": "4.2.2",
      "device_brand": "Verizon",
      "device_manufacturer": "Apple",
      "device_model": "iPhone 9,1",
      "carrier": "Verizon",
      "country": "United States",
      "region": "California",
      "city": "San Francisco",
      "dma": "San Francisco-Oakland-San Jose, CA",
      "language": "English",
      "price": 4.99,
      "quantity": 3,
      "revenue": -1.99,
      "productId": "Google Pay Store Product Id",
      "revenueType": "Refund",
      "location_lat": 37.77,
      "location_lng": -122.39,
      "ip": "127.0.0.1",
      "idfa": "AEBE52E7-03EE-455A-B3C4-E57283966239",
      "idfv": "BCCE52E7-03EE-321A-B3D4-E57123966239",
      "adid": "AEBE52E7-03EE-455A-B3C4-E57283966239",
      "android_id": "BCCE52E7-03EE-321A-B3D4-E57123966239",
      "event_id": 23,
      "session_id": 1396381378123,
      "insert_id": "5f0adeff-6668-4427-8d02-57d803a2b841"
    }
  ]
}

Parameters

Responses

This operation does not require authentication

UploadRequestBody

{
  "api_key": "my_amplitude_api_key",
  "events": [
    {
      "user_id": "[email protected]",
      "device_id": "C8F9E604-F01A-4BD9-95C6-8E5357DF265D",
      "event_type": "watch_tutorial",
      "time": 1396381378123,
      "event_properties": {
        "load_time": 0.8371,
        "source": "notification",
        "dates": [
          "monday",
          "tuesday"
        ]
      },
      "user_properties": {
        "age": 25,
        "gender": "female",
        "interests": [
          "chess",
          "football",
          "music"
        ]
      },
      "groups": {
        "team_id": "1",
        "company_name": [
          "Amplitude",
          "DataMonster"
        ]
      },
      "app_version": "2.1.3",
      "platform": "iOS",
      "os_name": "Android",
      "os_version": "4.2.2",
      "device_brand": "Verizon",
      "device_manufacturer": "Apple",
      "device_model": "iPhone 9,1",
      "carrier": "Verizon",
      "country": "United States",
      "region": "California",
      "city": "San Francisco",
      "dma": "San Francisco-Oakland-San Jose, CA",
      "language": "English",
      "price": 4.99,
      "quantity": 3,
      "revenue": -1.99,
      "productId": "Google Pay Store Product Id",
      "revenueType": "Refund",
      "location_lat": 37.77,
      "location_lng": -122.39,
      "ip": "127.0.0.1",
      "idfa": "AEBE52E7-03EE-455A-B3C4-E57283966239",
      "idfv": "BCCE52E7-03EE-321A-B3D4-E57123966239",
      "adid": "AEBE52E7-03EE-455A-B3C4-E57283966239",
      "android_id": "BCCE52E7-03EE-321A-B3D4-E57123966239",
      "event_id": 23,
      "session_id": 1396381378123,
      "insert_id": "5f0adeff-6668-4427-8d02-57d803a2b841"
    }
  ]
}

Properties

Event

{
  "user_id": "[email protected]",
  "device_id": "C8F9E604-F01A-4BD9-95C6-8E5357DF265D",
  "event_type": "watch_tutorial",
  "time": 1396381378123,
  "event_properties": {
    "load_time": 0.8371,
    "source": "notification",
    "dates": [
      "monday",
      "tuesday"
    ]
  },
  "user_properties": {
    "age": 25,
    "gender": "female",
    "interests": [
      "chess",
      "football",
      "music"
    ]
  },
  "groups": {
    "team_id": "1",
    "company_name": [
      "Amplitude",
      "DataMonster"
    ]
  },
  "app_version": "2.1.3",
  "platform": "iOS",
  "os_name": "Android",
  "os_version": "4.2.2",
  "device_brand": "Verizon",
  "device_manufacturer": "Apple",
  "device_model": "iPhone 9,1",
  "carrier": "Verizon",
  "country": "United States",
  "region": "California",
  "city": "San Francisco",
  "dma": "San Francisco-Oakland-San Jose, CA",
  "language": "English",
  "price": 4.99,
  "quantity": 3,
  "revenue": -1.99,
  "productId": "Google Pay Store Product Id",
  "revenueType": "Refund",
  "location_lat": 37.77,
  "location_lng": -122.39,
  "ip": "127.0.0.1",
  "idfa": "AEBE52E7-03EE-455A-B3C4-E57283966239",
  "idfv": "BCCE52E7-03EE-321A-B3D4-E57123966239",
  "adid": "AEBE52E7-03EE-455A-B3C4-E57283966239",
  "android_id": "BCCE52E7-03EE-321A-B3D4-E57123966239",
  "event_id": 23,
  "session_id": 1396381378123,
  "insert_id": "5f0adeff-6668-4427-8d02-57d803a2b841"
}

{
  "user_id": "[email protected]",
  "device_id": "C8F9E604-F01A-4BD9-95C6-8E5357DF265D",
  "event_type": "$identify",
  "time": 1396381378123,
  "user_properties": {
    "$set": {
      "age": 25,
      "gender": "female",
      "interests": [
      "chess",
      "football",
      "music"
    ]}
  },
  "event_id": 23,
  "session_id": 1396381378123,
  "insert_id": "5f0adeff-6668-4427-8d02-57d803a2b841"
}

{
  "user_id": "[email protected]",
  "device_id": "C8F9E604-F01A-4BD9-95C6-8E5357DF265D",
  "event_type": "$groupidentify",
  "time": 1396381378123,
  "groups": {
    "team_id": "1",
    "company_name": [
      "Amplitude",
      "DataMonster"
    ]
  },
  "group_properties": {
    "$set": {
      "start_date": "01/01/2017"
    }
  },
  "event_id": 23,
  "session_id": 1396381378123,
  "insert_id": "5f0adeff-6668-4427-8d02-57d803a2b841"
}

Properties

Options

Properties

"options": {
  "min_id_length": 5,
}

SuccessSummary

{
  "code": 200,
  "events_ingested": 50,
  "payload_size_bytes": 50,
  "server_upload_time": 1396381378123
}

Properties

InvalidRequestError

{
  "code": 400,
  "error": "Request missing required field",
  "missing_field": "api_key",
  "events_with_invalid_fields": {
    "time": [
      3,
      4,
      7
    ]
  },
  "events_with_missing_fields": {
    "event_type": [
      3,
      4,
      7
    ]
  }
}

Properties

SilencedDeviceID

{
    "code": 400,
    "eps_threshold": 100,
    "error": "Events silenced for device_id",
    "exceeded_daily_quota_devices":
    {},
    "silenced_devices":
    [
        "silenced_device_id_1",
        "silenced_device_id_2"
    ],
    "silenced_events":
    [
        5,
        6
    ],
    "throttled_devices":
    {
        "throttled_device_id_1": 0,
        "throttled_device_id_2": 100
    },
    "throttled_events":
    [
        3,
        4
    ]
}

Properties

PayloadTooLargeError

{
  "code": 413,
  "error": "Payload too large"
}

Properties

TooManyRequestsForDeviceError

{
  "code": 429,
  "error": "Too many requests for some devices and users",
  "eps_threshold": 1000,
  "throttled_devices": {
    "C8F9E604-F01A-4BD9-95C6-8E5357DF265D": 4000
  },
  "throttled_users": {
    "[email protected]": 4000
  },
  "exceeded_daily_quota_users": {
    "[email protected]": 500200
  },
  "exceeded_daily_quota_devices": {
    "A1A1A000-F01A-4BD9-95C6-8E5357DF265D": 500900
  },
  "throttled_events": [
    3,
    4,
    7
  ]
}

Properties

Status Codes