Events API

Ingest and read events with the REST API.

Send a single event

http

POST /v1/events

Ingests one event. Successful ingestion returns HTTP 202 Accepted: the event is queued for processing rather than returned synchronously.

json

{
  "type": "purchase",
  "userId": "user_842",
  "data": {
    "product": "Premium",
    "price": 19.99
  }
}

Request fields:

Field	Type	Description
`type`	string	Event type. Required. Must not start with `$`.
`userId`	string	Identifier of the user the event belongs to.
`groupId`	string	Identifier of the group the event belongs to.
`source`	string	Source key; resolved to a source for the project.
`data`	object	Event properties.
`context`	object	Contextual data, merged with server context.
`tags`	object	Arbitrary key/value tags.
`timestamp`	string	ISO 8601 timestamp. Defaults to the current time.

Response (202):

json

{
  "data": {
    "id": "e1f4c6d2-...",
    "projectId": "p_123",
    "type": "purchase",
    "timestamp": "2026-08-24T10:32:01.000Z",
    "userId": "user_842",
    "groupId": null,
    "sourceId": null,
    "data": { "product": "Premium", "price": 19.99 },
    "context": {},
    "tags": {},
    "createdAt": "2026-08-24T10:32:01.000Z"
  }
}

Single ingestion is rate limited to 1000 events per minute. Exceeding the limit returns429 with a Retry-After header.

Send a batch of events

http

POST /v1/events/batch

Ingests a batch of events in one request. Each event uses the same shape as a single event.

json

{
  "events": [
    { "type": "purchase", "data": { "product": "A" } },
    { "type": "page.navigated", "data": { "path": "/pricing" } }
  ]
}

Response (202):

json

{
  "data": {
    "events": [
      { "id": "e1f4c6d2-...", "type": "purchase" }
    ],
    "received": 2,
    "accepted": 2,
    "rejected": 0
  }
}

Invalid events are counted in rejected and reported under errors; valid events in the batch are still ingested. Batch ingestion is rate limited to 100 requests per minute, and a single batch can contain up to 1000 events.

List events

http

GET /v1/projects/:projectId/events?limit=50&type=purchase

Query parameters:

limit: number of events (1-100, default 50)
cursor: pagination cursor from a previous response
type: filter by event type
userId: filter by user id
source: filter by source key
search: search across type, user, data, and context
startDate: ISO timestamp for the start of the range
endDate: ISO timestamp for the end of the range

Response:

json

{
  "data": [ "event objects" ],
  "pagination": {
    "nextCursor": "...",
    "hasMore": true
  }
}

Bounds are inclusive: both startDate and endDate match events in the result window.

Get a single event

http

GET /v1/projects/:projectId/events/:eventId

Response:

json

{
  "data": {
    "id": "e1f4c6d2-...",
    "type": "purchase",
    "timestamp": "2026-08-24T10:32:01.000Z",
    "data": { "product": "Premium", "price": 19.99 }
  }
}

Returns 404 if the event does not exist in the project.

Internal events

Event type values that start with $ are reserved for Vanta internal events: $page, $identify, $group, $measure, $increment, $decrement, and $error. The SDK and API emit these on your behalf.