> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signa.so/llms.txt
> Use this file to discover all available pages before exploring further.
# List Events
> Read your organization's event ledger, with a replay checkpoint
**Beta.** The event ledger and its replay rail are stable enough to build on,
but the per-event `data` payloads are versioned by `payload_version` and their
shape is not yet frozen. Pin `payload_version` in your consumer and read the
[changelog](/changelog) before upgrading.
## Overview
Every webhook Signa sends you is also a row in your organization's event ledger, addressable by the same `evt_*` id that arrives in the `webhook-id` header. The ledger is append-only and retained for **30 days**.
Two ways to read it:
* **Newest first** (`sort=-id`, the default) with `cursor` — a browse/tail feed.
* **Oldest first** (`sort=id`) with `after` — a durable replay from a checkpoint you persist. This is the recovery path when your receiver was down: store the last `evt_*` you processed, and ask for everything after it.
Requires the `events:read` scope.
## Query Parameters
Page size (1-100).
Opaque cursor from the previous response. Cannot be combined with `after`.
`-id` (newest first) or `id` (oldest first). `after` requires `id`.
Exclusive `evt_*` replay checkpoint. Valid only with `sort=id`. Returns `410 replay_window_expired` when the checkpoint has aged out of the 30-day window.
Filter by event type(s), comma-separated: `alert.created`, `trademark.status_changed`, `office_action.issued`.
Filter by office code(s), comma-separated. WIPO ST.3 uppercase (`US`, `EM`); legacy acronym slugs (`uspto`, `euipo`) and `EU` are also accepted.
Filter by trademark ID (`tm_*`).
ISO date or timestamp — events recorded by Signa at or after this time.
Filter by the portfolio membership snapshot taken when the event was recorded. Applies to **every** family, `alert.created` included: an alert is in the portfolio only when its matched mark was a member at event time. Later membership changes never rewrite history. Requires `portfolios:manage`.
## Response
Always `"list"`.
Array of event summaries.
Event ID (`evt_*`, opaque). The same value arrives in the `webhook-id` header of the matching delivery.
Always `"event"`.
Event slug, e.g. `trademark.status_changed`.
The mark this event is about (`tm_*`), or `null` for families with no trademark identity.
WIPO ST.3 office code, or `null`.
When **Signa** produced the event: ingestion time for `trademark.*` and `office_action.*`, alert-creation time for `alert.created`. Not the office's own date — that is `source_date` on the detail body.
When the ledger row was written.
Alias of `recorded_at`.
Whether another page exists.
`{ cursor }` — opaque next-page cursor, `null` when exhausted.
## Errors
| Status | `type` | When |
| ------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| 400 | `validation_error` | Bad query parameter — `after` blank, `after` with `cursor`, `after` without `sort=id`, unknown `office_code` |
| 400 | `cursor_expired` / `cursor_invalid` | Malformed/tampered cursor, or one reused with different bound parameters |
| 403 | `forbidden` | Missing `events:read` (or `portfolios:manage` when using `portfolio_id`) |
| 404 | `not_found` | `portfolio_id` doesn't exist or belongs to another org |
| 410 | `replay_window_expired` | The `after` checkpoint is older than the 30-day retention window |
## Code Examples
```bash cURL theme={null}
# Tail the feed
curl "https://api.signa.so/v1/events?limit=20" \
-H "Authorization: Bearer sig_YOUR_KEY"
# Replay from a stored checkpoint
curl "https://api.signa.so/v1/events?sort=id&after=evt_3D7rZ9&limit=100" \
-H "Authorization: Bearer sig_YOUR_KEY"
```
```ts TypeScript theme={null}
// Replay everything you missed, oldest first.
const page = await signa.events.list({ sort: 'id', after: lastProcessedId, limit: 100 });
for await (const event of page) {
await handle(event);
}
```
```json 200 theme={null}
{
"object": "list",
"data": [
{
"id": "evt_3D7rZ9",
"object": "event",
"type": "trademark.status_changed",
"trademark_id": "tm_9vXq3Rmt",
"office_code": "US",
"occurred_at": "2026-08-14T09:10:00.000Z",
"recorded_at": "2026-08-14T09:10:02.000Z",
"created_at": "2026-08-14T09:10:02.000Z"
}
],
"has_more": false,
"pagination": { "cursor": null },
"request_id": "req_3vXq7RmT"
}
```
## Related Endpoints
* [Retrieve Event](/api-reference/monitoring/events/retrieve) - full detail with field-level before/after diffs
* [List Alerts](/api-reference/monitoring/alerts/list) - the alert resource an `alert.created` event wraps
* [Webhooks](/guides/monitoring/webhooks) - the push rail carrying the same `evt_*` ids