Track event
Events
Track event
POST /api/v1/events — emit a single user event.
POST
Track event
Emit a single event for a user. The endpoint accepts both the 10 canonical lifecycle event names and any custom name you choose.
Request
Body
External user ID. Should match the ID used in Upsert user. If the user hasn’t been identified yet, the event is buffered and attached when they’re first seen.
Event name. One of the canonical 10 or any custom string (snake_case recommended).
JSON-serialisable property bag. Optional — defaults to
{}.Response
Always
true on success. The event is enqueued and processed asynchronously.Examples
Common errors
401 auth_required
401 auth_required
Missing or malformed
Authorization header.403 forbidden
403 forbidden
API key valid but not authorised for this resource.
422 validation_failed
422 validation_failed
Body failed schema validation;
errors[0].field indicates the offending field.429 rate_limited
429 rate_limited
Wait
Retry-After seconds.5xx server_error
5xx server_error
Retry — the
Idempotency-Key prevents duplicates.