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

# Events

> Every event Tavrn emits, persisted for 30 days and queryable — reconcile missed webhooks or integrate without them.

## Overview

Each change Tavrn announces (a retrieval status change, an action request, new documents, an endpoint being disabled) is an **event**. Events are delivered to your [webhooks](/guides/v2/webhooks) and, independently, written to an event log you can read with `GET /v2/events` for 30 days.

The event body is identical in both places: the `id`, `type`, `created_at` and `data` you see in a webhook delivery are the same values `GET /v2/events/{id}` returns.

## Event object

```json theme={null}
{
  "id": "rr-06a28fdc7a8abfa2a1c98dd0562020ebb41ca740377930a736854d23a6c9881a",
  "object": "event",
  "type": "retrieval_request.status_changed",
  "created_at": "2026-02-01T14:22:10.000Z",
  "api_version": "v2",
  "request_id": null,
  "data": {
    "retrieval_request_id": "507f1f77bcf86cd799439011",
    "case_id": "507f1f77bcf86cd799439012",
    "public_updated_at": "2026-02-01T14:22:10.000Z",
    "status": "processing",
    "stage": "request_sent",
    "action_required_reason": null
  }
}
```

| Field | Description |
| - | - |
| `id` | Deterministic event ID. Equals the webhook body `id` and the `X-Webhook-Event-Id` header. |
| `type` | Event type. See the per-type `data` shapes in the [webhooks guide](/guides/v2/webhooks#retrieval-request-events). |
| `created_at` | When the triggering change was saved. |
| `api_version` | API version the event was rendered with. |
| `request_id` | Request ID of the API call that caused the event, or `null`. |
| `data` | Event payload; same as the webhook body `data`. |

## Listing events

```bash theme={null}
curl "https://enterprise.tavrn.ai/v2/events?type=retrieval_request.action_required&created_after=2026-02-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer tavrn_sk_live_..."
```

Filters: `type` (comma-separated, up to 20), `created_after`, `created_before`, `object_id` (for example a retrieval request ID). Results are newest first; follow `next` and `previous` for pagination.

**Scopes.** `webhooks:read` plus the read scope of the event family — `retrievals:read` for `retrieval_request.*`. Events from families your key cannot read are omitted; asking for one explicitly with `type` returns `403 insufficient_scope`.

## Reconciliation after an outage

1. Note the `created_at` of the last event you processed.
2. `GET /v2/events?created_after=<that time>` and page through `next`.
3. Process each event as you would a webhook delivery, deduplicating on `id`.

The event log covers 30 days. For anything older, use [incremental polling](/guides/v2/retrieval-guide#incremental-polling) on the resource itself.

## Related

* [`GET /v2/webhooks/{id}/deliveries`](/api-reference/v2/endpoint/webhooks/list-webhook-deliveries) — what happened to each delivery attempt.
* [Redeliver](/api-reference/v2/endpoint/webhooks/redeliver-webhook-delivery) — send an event to your endpoint again.