# Events API

Read `GET /v1/events` with a server secret key scoped for `events:read`. Filter by `types[]`, organization or directory when needed. Lists use `limit` (default 20, maximum 100) and an `after` cursor.

Events are returned oldest first by dispatch position. Store the last successfully processed event ID as your forward cursor and use `next_cursor` for continued pagination. A late-committed event must not be skipped by sorting creation timestamps or IDs yourself.

The envelope includes `id`, `object=event`, `type`, `created_at`, `environment`, `api_version` and `data`; organization, directory and sequence are present when applicable. Validate the envelope and the data for the event type before applying effects.

Persist your checkpoint with the corresponding effects or durable work item. Deduplicate by event ID across webhook delivery and API catch-up. If processing fails, keep the earlier cursor and retry safely.

Use `GET /v1/events/{event}` to inspect an individual event in the same environment. Treat payloads as sensitive directory/customer data; avoid logging entire event bodies.

See [management API](/reference/api/management/) for exact parameters and [ordering](/directory-sync/ordering/) for per-directory sequences.
