> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flokitai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch events

> Send multiple events in a single request for high-throughput or historical imports.

Use the batch endpoint to send up to 1,000 events per request. Ideal for historical imports, nightly syncs, or high-volume server-side instrumentation where making one request per event is impractical.

**Endpoint:** `POST /v1/batch/events`

***

## Send a batch

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.flokit.ai/v1/batch/events \
    -H "Authorization: Bearer $FLOKIT_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "events": [
        {
          "event": "paywall_viewed",
          "user_id": "usr_abc123",
          "timestamp": "2024-03-15T14:20:00Z",
          "properties": {
            "paywall_id": "pw_annual_v3",
            "context": "onboarding_step_3"
          }
        },
        {
          "event": "trial_started",
          "user_id": "usr_abc123",
          "timestamp": "2024-03-15T14:22:00Z",
          "properties": {
            "plan_id": "plan_annual_usd",
            "trial_length_days": 7,
            "paywall_id": "pw_annual_v3"
          }
        },
        {
          "event": "subscription_started",
          "user_id": "usr_abc123",
          "timestamp": "2024-03-22T14:22:00Z",
          "properties": {
            "plan_id": "plan_annual_usd",
            "revenue": 49.99,
            "currency": "USD",
            "transaction_id": "txn_3OZ9kL2eZvKYlo2C0FL1nGdU",
            "trial_converted": true,
            "store": "apple"
          }
        }
      ]
    }'
  ```

  ```typescript Node.js / TypeScript theme={null}
  const events = [
    {
      event: 'paywall_viewed',
      user_id: 'usr_abc123',
      timestamp: '2024-03-15T14:20:00Z',
      properties: {
        paywall_id: 'pw_annual_v3',
        context: 'onboarding_step_3',
      },
    },
    {
      event: 'trial_started',
      user_id: 'usr_abc123',
      timestamp: '2024-03-15T14:22:00Z',
      properties: {
        plan_id: 'plan_annual_usd',
        trial_length_days: 7,
        paywall_id: 'pw_annual_v3',
      },
    },
    {
      event: 'subscription_started',
      user_id: 'usr_abc123',
      timestamp: '2024-03-22T14:22:00Z',
      properties: {
        plan_id: 'plan_annual_usd',
        revenue: 49.99,
        currency: 'USD',
        transaction_id: 'txn_3OZ9kL2eZvKYlo2C0FL1nGdU',
        trial_converted: true,
        store: 'apple',
      },
    },
  ];

  const response = await fetch('https://api.flokit.ai/v1/batch/events', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FLOKIT_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ events }),
  });

  const data = await response.json();
  ```
</CodeGroup>

***

## Response

```json theme={null}
{
  "status": "ok",
  "accepted": 3,
  "rejected": 0,
  "event_ids": [
    "evt_01hx4j7k9m2n3p5q6r8s",
    "evt_01hx4j7k9m2n3p5q6r9t",
    "evt_01hx4j7k9m2n3p5q6r0u"
  ],
  "errors": []
}
```

If some events fail validation, the response still returns `200 OK`. Successfully validated events are processed; rejected events appear in the `errors` array with the event index and reason. Your application should inspect `rejected` and `errors` after each batch call.

```json theme={null}
{
  "status": "ok",
  "accepted": 2,
  "rejected": 1,
  "event_ids": [
    "evt_01hx4j7k9m2n3p5q6r8s",
    "evt_01hx4j7k9m2n3p5q6r9t"
  ],
  "errors": [
    {
      "index": 2,
      "event": "subscription_started",
      "reason": "Missing required field: currency"
    }
  ]
}
```

***

## Rate limits

| Limit               | Value             |
| ------------------- | ----------------- |
| Events per request  | 1,000             |
| Requests per minute | 100 per workspace |

For higher throughput, contact FloKit — dedicated ingest capacity is available for enterprise workspaces.

***

## Historical import

For initial data backfills exceeding 100,000 events, use **FloKit → Data → Import** to upload a CSV file. For larger datasets or schema mapping assistance, contact FloKit for a managed bulk upload.

When sending a historical backfill via the batch API:

* Sort events by `timestamp` within each batch to help FloKit process them in order.
* Use the `Idempotency-Key` header on each batch request so retries are safe.
* Spread large imports across multiple requests rather than waiting for a single large upload to complete.