---
title: "Record a batch of events"
description: "Deliver gzip-compressed events with item-level acceptance results."
api: POST https://i.nuxie.ai/batch
authMethod: none
playground: simple
search:
  tags: ["api", "app", "reference"]
  keywords: ["batch", "gzip", "historical_migration", "eventIds", "partial", "Content-Encoding"]
---

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-Encoding`** · header · `string` · required

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

## Request body

- **`apiKey`** · body · `string` · required

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

- **`batch`** · body · `object[]` · required

  Between 1 and 1,000 events. Each item uses the fields from [Record an event](/docs/api-reference/app/event#request-body); the top-level `apiKey` authenticates every item.

- **`historical_migration`** · body · `boolean`

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

## Response

- **`status`** · `string` · required

  `success`, `partial`, or `error`.

- **`accepted`** · `integer` · required

  Number of events accepted into the queue.

- **`processed`** · `integer` · required

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

- **`failed`** · `integer` · required

  Number of failed items.

- **`total`** · `integer` · required

  Number of submitted items.

- **`queued`** · `boolean` · required

  Whether the response reports events queued for processing.

- **`validationFailed`** · `integer` · required

  Items with invalid fields.

- **`rejectedFailed`** · `integer` · required

  Items that require another endpoint or cannot enter the queue.

- **`enqueueFailed`** · `integer`

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

- **`eventIds`** · `string[]`

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

- **`errors`** · `object[]`

  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.

```sh title="cURL with gzip"
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 @-
```

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