> ## Documentation Index
> Fetch the complete documentation index at: https://docs.traversal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Event Logs API

> Query the audit trail of changes made within your organization — admin-only access for compliance reviews and SIEM ingestion.

> [!WARNING]
>
> **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](https://docs.traversal.com/api/authentication.md) to create an API key. For base URL, error envelope, and generic status codes, see the [API overview](https://docs.traversal.com/api/overview.md).

> [!NOTE]
>
> 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](#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

```json theme={null}
{
  "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

```json theme={null}
{
  "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?" }
  }
}
```

> [!TIP]
>
> 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](https://docs.traversal.com/api/sessions.md) convention. `limit` is capped at 100.

```bash theme={null}
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](https://docs.traversal.com/api/overview.md#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`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.