Batch events - FloKit.AI

Part of the v1 REST API design-partner preview — no public host yet. YOUR-FLOKIT-API-HOST is a placeholder your FloKit team fills in when you get access.

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://YOUR-FLOKIT-API-HOST/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"
        }
      }
    ]
  }'

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://YOUR-FLOKIT-API-HOST/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();

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

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.