Event Logs API

Beta. The Event Logs API is available under /v0/event-logs while we collect feedback. The endpoint may change before it stabilizes at /v1. Contact your Traversal point of contact before relying on it for production workloads.

The Event Logs API exposes every change made to your organization’s data — integrations created, users invited, sessions started, and more. It’s the same audit trail you can see in the admin UI, surfaced through a stable contract designed for SOC2 / compliance reviews and SIEM ingestion. All endpoints require authentication — see Authentication to create an API key. For base URL, error envelope, and generic status codes, see the API overview.

The Event Logs API requires the admin role. API keys created by non-admins cannot read event logs.

Endpoints

See the Endpoints section in the sidebar for the full API reference, generated from the OpenAPI spec.

Event shape

Every event log row has the same envelope:

id — stable identifier for the event.
time — UTC timestamp of when the event happened.
type — dotted <resource>.<action> string identifying the event (e.g. integrations.update, auth.login).
user_id / user_email — the user who triggered the event. Both can be null for system-driven events or when the user no longer exists.
data — the payload. The shape of data depends on type — see The data field below.

The `type` field

type identifies which event you’re looking at and determines the shape of data. The full set of values is listed in the API reference — broadly:

Resource	Actions
`integrations`	`create`, `update`, `delete`
`api_keys`	`create`, `delete`
`users`	`invite_sent`, `invite_accepted`, `role_granted`, `archive`
`auth`	`login`, `logout`
`sessions`	`create`, `update`, `delete`

New (resource, action) pairs may be added over time. Clients should treat unknown type values gracefully rather than hard-fail.

The `data` field

data carries one of two shapes depending on the action:

Lifecycle events (everything except .update) — data is a snapshot of the resource at the time of the event. The exact fields vary by type.
.update events — data is a diff: a map of field names to { "old": <previous>, "new": <current> }. Only fields that actually changed are present.

Example: lifecycle event

{
  "id": 482913,
  "time": "2026-05-27T14:31:02Z",
  "type": "integrations.create",
  "user_id": "a9c2e3b0-...",
  "user_email": "alice@acme.com",
  "data": {
    "id": "int-prod-datadog",
    "name": "prod-datadog",
    "type": "datadog",
    "created_by_user_id": "a9c2e3b0-...",
    "created_by_user_email": "alice@acme.com"
  }
}

Example: update event

{
  "id": 482914,
  "time": "2026-05-27T14:32:05Z",
  "type": "sessions.update",
  "user_id": "a9c2e3b0-...",
  "user_email": "alice@acme.com",
  "data": {
    "status": { "old": "idle", "new": "follow_up_running" },
    "user_message": { "old": null, "new": "why did the queue back up?" }
  }
}

Check type first to know which data shape to expect.

Filtering

The list endpoint supports four optional filters:

Filter	Effect
`start_time`	Inclusive lower bound on the event timestamp (ISO-8601 UTC).
`end_time`	Exclusive upper bound on the event timestamp. `400` if `end_time <= start_time`.
`type`	Exact match on the dotted `<resource>.<action>` value.

Combine them freely — e.g. ?type=auth.login&start_time=2026-05-01T00:00:00Z&end_time=2026-06-01T00:00:00Z returns every login during May 2026.

Pagination

Pagination uses page + limit query parameters, with count / prev / next / total metadata in the response — matching the Sessions API convention. limit is capped at 100.

curl -s "$TRAVERSAL_BASE_URL/v0/event-logs?page=1&limit=50" \
  -H "Authorization: Bearer $TRAVERSAL_API_KEY"

If both page and limit are omitted, all matching rows are returned in a single response. Results are ordered newest-first by id.

Rate limits

The endpoint is limited to 100 requests per minute. Hitting the limit returns 429 Too Many Requests with a Retry-After header — wait the suggested number of seconds and retry.

Common use cases

SOC2 / compliance review — pull every event in a date range, archive externally.
SIEM ingestion — poll with start_time set to the timestamp of the most recent ingested row.
Forensic lookup — filter on type (e.g. auth.login) to investigate authentication-event timing around an incident.

Event-logs-specific errors

In addition to the generic status codes, the Event Logs API returns:

Status code	Meaning	When it occurs
`400`	Bad Request	Invalid `type` value, or `end_time <= start_time`.
`403`	Forbidden	The API key’s user does not hold the admin role.
`429`	Too Many Requests	Per-gateway rate limit exceeded. Includes `Retry-After`.

Get Started

Architecture

Set up

Using Traversal

API

Security & Trust

Changelog

Endpoints

Event shape

The `type` field

The `data` field

Example: lifecycle event

Example: update event

Filtering

Rate limits

Common use cases

Event-logs-specific errors

​Endpoints

​Event shape

​The type field

​The data field

​Example: lifecycle event

​Example: update event

​Filtering

​Pagination

​Rate limits

​Common use cases

​Event-logs-specific errors

Endpoints

Event shape

The `type` field

The `data` field

Example: lifecycle event

Example: update event

Filtering

Pagination

Rate limits

Common use cases

Event-logs-specific errors