# List tags

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

`GET /v1/tags`

Requires an API key with the `tags: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.

Returns the workspace's tags sorted by name (ignoring case), each with how many campaigns, journeys, segments and templates carry it. Results are cursor-paginated: pass `meta.pagination.nextCursor` back as `cursor` until it comes back `null`. The cursor is opaque — do not construct or parse one.

## 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–64 characters) — Part of the tag's name, ignoring case: what a picker types.

## 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 `Tag` 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.

- `id` (string, required, uuid)
- `name` (string, required)
- `usage` (object, required) — How many items of each kind carry the tag.
  - `campaigns` (integer, required, min 0)
  - `journeys` (integer, required, min 0)
  - `segments` (integer, required, min 0)
  - `templates` (integer, required, min 0)
- `createdAt` (string, required, date-time)
- `updatedAt` (string, required, date-time)

## Example

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

Response `200`:

```json
{
  "data": [
    {
      "id": "0192f3e0-2b3c-7d4e-9f50-6b7c8d9e0f1a",
      "name": "BF",
      "usage": {
        "campaigns": 2,
        "journeys": 0,
        "segments": 1,
        "templates": 0
      },
      "createdAt": "2026-10-01T09:30:00.000Z",
      "updatedAt": "2026-10-01T09:30:00.000Z"
    },
    {
      "id": "0192f3e0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
      "name": "Black Friday",
      "usage": {
        "campaigns": 4,
        "journeys": 1,
        "segments": 2,
        "templates": 3
      },
      "createdAt": "2026-10-01T09:30:00.000Z",
      "updatedAt": "2026-10-02T14:05:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 20,
      "nextCursor": null
    }
  }
}
```