# Retrieve a list's usage

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

`GET /v1/lists/{id}/usage`

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

Works with integration, agent and partner keys.

Returns what names the list: campaigns whose audience, rules or exclusions name it, or whose content has a block shown only to, or hidden from, its members, forms that add people to it, goals whose rules name it, journeys whose rules or steps name it, segments whose rules name it, and templates (the draft or the published version) and shared blocks with such a block, up to 50 of each (`hasMore` when a kind holds more). Deleting the list is refused (409 `IN_USE`) while any of them is a campaign not yet sent or cancelled (`draft`, `scheduled`, `testing` for an A/B test, or `sending`), a published form not archived, a goal not retired, an `active` or `paused` journey, a segment, a template or a shared block. Draft or archived forms, sent or cancelled campaigns, retired goals and draft or ended journeys do not block it.

## Path parameters

- `id` (string, required, uuid) — The list's id.

## 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 `ListUsage` in `data`. Otherwise returns an error; [Errors](https://kirora.io/docs/api/reference/errors) lists every code and which to retry.

- `campaigns` (object[], required)
  - `id` (string, required, uuid)
  - `name` (string, required)
  - `status` (string, required, one of `draft`, `scheduled`, `sending`, `testing`, `sent`, `cancelled`)
- `forms` (object[], required)
  - `id` (string, required, uuid)
  - `name` (string, required)
- `goals` (object[], required)
  - `id` (string, required, uuid)
  - `name` (string, required)
- `journeys` (object[], required)
  - `id` (string, required, uuid)
  - `name` (string, required)
  - `status` (string, required, one of `draft`, `active`, `paused`, `ended`)
- `segments` (object[], required)
  - `id` (string, required, uuid)
  - `name` (string, required)
- `templates` (object[], required)
  - `id` (string, required, uuid)
  - `name` (string, required)
- `sharedBlocks` (object[], required)
  - `id` (string, required, uuid)
  - `name` (string, required)
- `hasMore` (boolean, required) — More use it than are listed: each list stops at 50.

## Example

```bash
curl https://api.kirora.io/v1/lists/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/usage \
  -H "Authorization: Bearer $KIRORA_API_KEY"
```

Response `200`:

```json
{
  "data": {
    "campaigns": [
      {
        "id": "0192f3d3-5e6f-7071-8c83-9e0f1a2b3c4d",
        "name": "October newsletter",
        "status": "scheduled"
      }
    ],
    "forms": [
      {
        "id": "0192f3f1-2b3c-7d4e-9f50-6b7c8d9e0f12",
        "name": "Newsletter sign-up"
      }
    ],
    "goals": [],
    "journeys": [],
    "segments": [],
    "templates": [],
    "sharedBlocks": [],
    "hasMore": false
  }
}
```