Record a batch of events

Deliver gzip-compressed events with item-level acceptance results.

POSThttps://i.nuxie.ai/batch

Send up to 1,000 events in one request. Compress the JSON body with gzip; uncompressed JSON is rejected. The compressed body must be at most 16 MiB.

Headers

Content-Encodingheaderstringrequired

Must be gzip. Set Content-Type: application/json as well.

Request body

apiKeybodystringrequired

Publishable key for the app platform. A pk_test_ key selects test data; a pk_live_ key selects live data. Copy it from Connect your app.

batchbodyobject[]required

Between 1 and 1,000 events. Each item uses the fields from Record an event; the top-level apiKey authenticates every item.

historical_migrationbodyboolean

Set to true to sort historical events by timestamp before queueing. Leave unset for normal app traffic.

Response

statusstringrequired

success, partial, or error.

acceptedintegerrequired

Number of events accepted into the queue.

processedintegerrequired

Alias of accepted; does not mean analytics have finished updating.

failedintegerrequired

Number of failed items.

totalintegerrequired

Number of submitted items.

queuedbooleanrequired

Whether the response reports events queued for processing.

validationFailedintegerrequired

Items with invalid fields.

rejectedFailedintegerrequired

Items that require another endpoint or cannot enter the queue.

enqueueFailedinteger

Items that could not be queued, when a queue failure occurs.

eventIdsstring[]

IDs of accepted events. Omitted when no events were accepted.

errorsobject[]

Failed item details, when present. Each includes index, event, and error, with lane and endpoint when relevant.

A partial result does not roll back accepted events. Check the body even when the HTTP status is 200: a batch containing only invalid events can return status: "error" with accepted: 0.

Correct invalid items before resubmitting. Retry transient failures with their original event UUIDs. If the whole request’s outcome is unknown, you can retry the batch with the same UUIDs so accepted events are deduplicated.

cat > events.json <<'JSON'
{
  "apiKey": "pk_test_example",
  "batch": [
    {
      "event": "screen_viewed",
      "distinct_id": "user-456",
      "properties": { "screen": "home" },
      "uuid": "018f55a9-9ec4-7d7a-9b4a-1dbe8cc58410"
    }
  ]
}
JSON

gzip -c events.json | curl https://i.nuxie.ai/batch \
  --header 'Content-Type: application/json' \
  --header 'Content-Encoding: gzip' \
  --data-binary @-

{
  "status": "success",
  "accepted": 1,
  "processed": 1,
  "failed": 0,
  "total": 1,
  "queued": true,
  "validationFailed": 0,
  "rejectedFailed": 0,
  "eventIds": ["018f55a9-9ec4-7d7a-9b4a-1dbe8cc58410"]
}