# List the event catalogue

Source: https://kirora.io/docs/api/reference/listEventCatalog

`GET /v1/events/catalog`

Requires an API key with the `events:read` scope. [About keys and scopes](https://kirora.io/docs/api/reference/authentication)

Works with integration, agent and partner keys. Also available to embed sessions.

The workspace's event names, for the data index and for trigger, rule and goal pickers: Kirora's system names, each name the workspace has sent, and each one a person defined before sending it. Each has its `origin` (`system`, `standard` or `custom`), whether it has events (`recorded`), its description, when it was last seen, its last 30 days and how many journeys, segments, campaigns and goals read it. The figures are counted at most 15 minutes before `meta.countedAt`; a name sent for the first time is listed at once. `query`, `origin` and `recorded` filter, and `sort` orders, across every page. Standard names not yet sent are in `GET /events/standard-names`. Only the first page has `meta.nameUsage`: the names counted against the workspace's limit of 1,000, defined ones included; past it a new name is refused with `EVENT_NAME_LIMIT_REACHED`.

## Query parameters

- `limit` (integer, optional, min > 0, max 100, default `20`) — How many items a page holds: 1 to 100, 20 by default.
- `cursor` (string, optional, 1–2,048 characters) — Where the page starts: the previous page's `meta.pagination.nextCursor`. Omit it for the first page, and send the same filters with it.
- `query` (string, optional, 1–128 characters) — Only names containing this, ignoring case.
- `origin` (string, optional, one of `system`, `standard`, `custom`) — Only names of this origin.
- `recorded` (string, optional, one of `true`, `false`) — `true`: only names with events; `false`: only names without, such as one defined before it was sent.
- `sort` (string, optional, one of `-lastSeenAt`, `lastSeenAt`, `-last30DaysCount`, `last30DaysCount`, `name`, `-name`, default `"-lastSeenAt"`) — A field ascending, or `-field` descending; ties go by name. A name with no events sorts last by `lastSeenAt` either way.

## Header parameters

- `Kirora-Workspace` (string, optional, pattern `^[A-Za-z0-9._:-]{1,128}$`) — Partner keys only: the child workspace to act in, by the external id the partner gave it. Without it, a partner key acts in its own workspace. Any other key that sends it is refused with 403, and an unknown workspace is 404.

## Returns

Returns `200 OK` with a list of `EventName` objects in `data`, and the next page's cursor in `meta` (see [pagination](https://kirora.io/docs/api/reference/pagination)). Otherwise returns an error; [Errors](https://kirora.io/docs/api/reference/errors) lists every code and which to retry.

- `name` (string, required)
- `origin` (string, required, one of `system`, `standard`, `custom`)
- `recorded` (boolean, required) — Whether the workspace has events of it. False for a name defined before it was sent, and for a system name Kirora has not recorded yet.
- `description` (string | null, required) — The workspace's description, else Kirora's meaning for a system or standard name; null when neither. Plain text.
- `lastSeenAt` (string | null, required, date-time) — When its latest event happened; null when it has none.
- `last30DaysCount` (integer, required, min 0) — Events of it that happened in the last 30 days.
- `usedByCount` (integer, required, min 0) — Journeys, segments, campaigns, conversion goals and active workspace goals that read it; the summary names them.

## Example

```bash
curl https://api.kirora.io/v1/events/catalog \
  -H "Authorization: Bearer $KIRORA_API_KEY"
```

Response `200`:

```json
{
  "data": [
    {
      "name": "Order Completed",
      "origin": "standard",
      "recorded": true,
      "description": "A contact paid for an order: order_id, total, currency, products[].",
      "lastSeenAt": "2026-10-25T18:42:07.000Z",
      "last30DaysCount": 412,
      "usedByCount": 3
    },
    {
      "name": "Webinar Registered",
      "origin": "custom",
      "recorded": true,
      "description": "A contact signed up for a live webinar.",
      "lastSeenAt": "2026-10-24T09:15:00.000Z",
      "last30DaysCount": 58,
      "usedByCount": 1
    },
    {
      "name": "Plan Upgraded",
      "origin": "custom",
      "recorded": false,
      "description": "A contact moved to a paid plan. Defined ahead of the app sending it.",
      "lastSeenAt": null,
      "last30DaysCount": 0,
      "usedByCount": 1
    }
  ],
  "meta": {
    "pagination": {
      "limit": 3,
      "nextCursor": "eyJsYXN0U2VlbkF0IjpudWxsLCJsYXN0MzBEYXlzQ291bnQiOjAsIm5hbWUiOiJQbGFuIFVwZ3JhZGVkIn0"
    },
    "countedAt": "2026-10-26T08:00:00.000Z",
    "nameUsage": {
      "count": 37,
      "limit": 1000
    }
  }
}
```