Bulk track events
Events
Bulk track events
POST /api/v1/events/bulk — backfill up to 1,000 events in one request.
POST
Bulk track events
The backfill counterpart to single-event track. Send up to 1,000 event records in one POST. Replaces the older
/api/v1/events/batch endpoint for new integrations — the bulk endpoint reports per-record errors instead of failing the whole batch.
SDK is the recommended path.
vf.events.bulk() wraps this endpoint with strong typing and pairs with chunk() for backfills larger than 1,000 records.Request
Body
Array of event records. Each entry has the same shape as the single-event body. Minimum 1, maximum 1,000 records.
Response
Records that passed validation and were enqueued.
Records that failed validation. Each has a corresponding entry in
data.errors.Per-record validation failures with the original array
index.Total records in the request.
accepted + rejected === meta.received.Idempotency is automatic. The server-side
events_dedupe_unique partial index on (project_id, tracked_user_id, name, occurred_at) means re-sending the same event is a no-op. Retry any chunk that returns 429 or 5xx — duplicates are silently dropped.Examples
Common errors
401 auth_required
401 auth_required
Missing or malformed
Authorization header.400 validation_failed
400 validation_failed
Envelope failed validation:
events missing, not an array, empty, or > 1,000 records. Per-record validation failures surface in data.errors.429 rate_limited
429 rate_limited
Standard per-project rate limit; honor
Retry-After.429 backfill_queue_full
429 backfill_queue_full
The project’s ingest queue is saturated (50,000+ jobs waiting or delayed). Back off, drain, then resume in smaller chunks.
5xx server_error
5xx server_error
Retry the same chunk — per-event dedup makes duplicate ingestion a no-op.
Sizing
Max records per request
1,000
Recommended chunk size
1,000
Backfill queue cap
50,000 waiting jobs / project