# List event names

`GET /v1/events/names`

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

Event names to offer in triggers and goal pickers, each with its `origin`: `system` (recorded by Kirora), `suggested` (the standard e-commerce events, Segment v2 names, whether or not the workspace has sent them) or `observed`. The first page carries every preset name ahead of its `limit` observed ones; later pages carry observed names only, and only the first page has `meta.nameUsage`: the distinct names the workspace has tracked against its limit of 1,000; past it a new name is refused with `EVENT_NAME_LIMIT_REACHED`.

## Query parameters

- `limit` (integer, optional, min > 0, max 100, default `20`)
- `cursor` (string, optional, 1–2048 characters)

## Returns

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

- `name` (string, required)
- `origin` (string, required, one of `system`, `suggested`, `observed`)
- `recorded` (boolean, required) — Whether the workspace has tracked it; always true for an observed name.

## Example

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

Response `200`:

```json
{
  "data": [
    {
      "name": "Weekend specials",
      "origin": "system",
      "recorded": true
    }
  ],
  "meta": {
    "pagination": {
      "limit": 1,
      "nextCursor": "nextCursor_example"
    },
    "nameUsage": {
      "count": 0,
      "limit": 1
    }
  }
}
```