# List campaigns

`GET /v1/campaigns`

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

Returns campaigns in this organization, newest first by default. Pass `status` to list only campaigns in that state. 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`)
- `cursor` (string, optional, 1–2048 characters)
- `q` (string, optional, 1–200 characters)
- `status` (string, optional, one of `draft`, `scheduled`, `sending`, `sent`, `cancelled`) — Only campaigns in this status.
- `archived` (string, optional, one of `true`, `false`, default `"false"`) — `true` lists archived campaigns only; unset or `false` leaves them out.

## Returns

Returns `200 OK` with a list of `CampaignListItem` 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.

- `id` (string, required, uuid)
- `name` (string, required)
- `channels` (string[], required) — The channels it sends on.
- `groupId` (string | null, required, uuid) — The group it goes to, if any.
- `segmentId` (string | null, required, uuid) — The segment it goes to, if any.
- `audienceRules` (object | null, required) — Inline rules choosing the audience, if any. At most one audience is set.
  - One of: **Match all**
    - `all` (object[], required, at least 1 item, at most 20 items) — Every rule or nested group must match.
  - One of: **Match any**
    - `any` (object[], required, at least 1 item, at most 20 items) — At least one rule or nested group must match.
- `topicId` (string | null, required, uuid) — Sends only to contacts the topic reaches; `null` sends to everyone with consent.
- `status` (string, required, one of `draft`, `scheduled`, `sending`, `sent`, `cancelled`) — Where the campaign is in its lifecycle.
- `sendAt` (string | null, required, date-time) — When it is scheduled to send, if at all.
- `localSendAt` (string | null, required) — Set for a local-time send: the wall-clock time each contact receives it at.
- `archivedAt` (string | null, required, date-time) — When it was archived; archived campaigns are left out of the list by default.
- `createdAt` (string, required, date-time)
- `updatedAt` (string, required, date-time)

## Example

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

Response `200`:

```json
{
  "data": [
    {
      "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
      "name": "Weekend specials",
      "channels": [
        "email"
      ],
      "groupId": "018f2a4e-6b1c-7d3e-9f40-532211a15a6b",
      "segmentId": "018f2a4e-6b1c-7d3e-9f40-243b225b5a6b",
      "audienceRules": {
        "all": [
          {
            "type": null,
            "field": null,
            "operator": null
          }
        ]
      },
      "topicId": "018f2a4e-6b1c-7d3e-9f40-84e01f695a6b",
      "status": "draft",
      "sendAt": "2030-03-14T09:30:00Z",
      "localSendAt": "localSendAt_example",
      "archivedAt": "2030-03-14T09:30:00Z",
      "createdAt": "2030-03-14T09:30:00Z",
      "updatedAt": "2030-03-14T09:30:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 1,
      "nextCursor": "nextCursor_example"
    }
  }
}
```