Skip to main content
POST
/
api
/
v1
/
events
/
batch
Batch track events
curl --request POST \
  --url https://api.example.com/api/v1/events/batch \
  --header 'Content-Type: application/json' \
  --data '
{
  "events": [
    {}
  ]
}
'
{
  "data.accepted": true
}

Documentation Index

Fetch the complete documentation index at: https://docs.vibefollow.com/llms.txt

Use this file to discover all available pages before exploring further.

Endpoint behaviour is stable; the SDK batching wrapper is the recommended path today. Use vf.events.batch() for buffered emission — it auto-flushes by size and age and handles retries.
Emit multiple events in a single POST. Useful for backfills, data-warehouse syncs, and any path where per-event HTTP overhead dominates.

​
Request

POST /api/v1/events/batch HTTP/1.1
Host: api.vibefollow.com
Authorization: Bearer sk_live_••••
Content-Type: application/json
Idempotency-Key: 7b6c7e9e-2c2d-4a8d-9d3a-4f3d2c1b0a99

​
Body

{
  "events": [
    {
      "external_user_id": "usr_42",
      "name": "user_signed_up",
      "properties": { "plan": "trial" }
    },
    {
      "external_user_id": "usr_42",
      "name": "trial_started",
      "properties": { "trialDays": 14 }
    }
  ]
}
​
events
Event[]
required
Array of events. Each event has the same shape as the single-event endpoint body (external_user_id, name, properties). Maximum 500 events per batch.

​
Response

HTTP/1.1 202 Accepted
Content-Type: application/json

{ "data": { "accepted": true } }
​
data.accepted
boolean
Always true on success. The response confirms the batch was enqueued. Per-event validation happens server-side.
If one event in the batch fails validation, the whole batch is rejected with 422 and errors[0].field indicates the offending event index (e.g. events[3].external_user_id).

​
Examples

import { VibeFollow } from '@vibefollow/sdk';

const vf = new VibeFollow({ apiKey: process.env.VIBEFOLLOW_API_KEY! });
const batch = vf.events.batch({ maxSize: 100, maxAgeMs: 5_000 });

for (const row of historicalEvents) {
  batch.track(row.name, row.userId, row.properties);
}

await batch.flush();

​
Common errors

Missing or malformed Authorization header.
Any event in the batch failed validation; errors[0].field indicates the offending index.
Wait Retry-After seconds.
Retry — the Idempotency-Key prevents duplicates.

​
Sizing

Max events per batch

500

Max body size

5 MB

Max properties per event

100 keys, 1 MB total
If you hit these limits, split the batch on your side. The SDK’s events.batch() defaults to maxSize: 100, which fits comfortably under all of them.