Skip to main content
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

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"
        }
      }
    ]
  }'

​
Response

{
  "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. 
{
  "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

LimitValue
Events per request1,000
Requests per minute100 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.