# Retrieve campaign statistics

`GET /v1/campaigns/{id}/stats`

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

Aggregate delivery and engagement counters for one campaign. The top-level counters span every channel, so they count messages: an email-and-push campaign to 100 people reports `sent: 200`. Use `recipients` for people and `byChannel` for each channel. Counters continue to move after a send completes, as opens, clicks and bounces arrive.

## Path parameters

- `id` (string, required, uuid)

## Returns

Returns `200 OK` with a `CampaignStats` in `data`. Otherwise returns an error; [Errors](/docs/api/errors) lists every code and which to retry.

- `campaignId` (string, required, uuid)
- `recipients` (integer, required, min 0, max 9007199254740991) — People the campaign went to.
- `queued` (integer, required, min 0, max 9007199254740991) — Messages waiting to be sent.
- `sending` (integer, required, min 0, max 9007199254740991) — Messages being handed to the provider.
- `skipped` (integer, required, min 0, max 9007199254740991) — Messages not sent; see `skippedByReason`.
- `sent` (integer, required, min 0, max 9007199254740991) — Messages handed to the provider.
- `failed` (integer, required, min 0, max 9007199254740991) — Messages that could not be sent.
- `delivered` (integer, required, min 0, max 9007199254740991) — Messages confirmed delivered.
- `bounced` (integer, required, min 0, max 9007199254740991) — Messages the recipient server rejected.
- `complained` (integer, required, min 0, max 9007199254740991) — Messages the recipient marked as spam.
- `opened` (integer, required, min 0, max 9007199254740991) — Messages opened at least once.
- `clicked` (integer, required, min 0, max 9007199254740991) — Messages with a link clicked at least once.
- `unsubscribed` (integer, required, min 0, max 9007199254740991) — Recipients who opted out through this campaign's link.
- `total` (integer, required, min 0, max 9007199254740991) — All messages created.
- `byChannel` (object, required) — The same counters per channel; a channel the campaign skips is absent.
  - `email` (CampaignMessageCounts, optional)
    - `queued` (integer, required, min 0, max 9007199254740991) — Messages waiting to be sent.
    - `sending` (integer, required, min 0, max 9007199254740991) — Messages being handed to the provider.
    - `skipped` (integer, required, min 0, max 9007199254740991) — Messages not sent; see `skippedByReason`.
    - `sent` (integer, required, min 0, max 9007199254740991) — Messages handed to the provider.
    - `failed` (integer, required, min 0, max 9007199254740991) — Messages that could not be sent.
    - `delivered` (integer, required, min 0, max 9007199254740991) — Messages confirmed delivered.
    - `bounced` (integer, required, min 0, max 9007199254740991) — Messages the recipient server rejected.
    - `complained` (integer, required, min 0, max 9007199254740991) — Messages the recipient marked as spam.
    - `opened` (integer, required, min 0, max 9007199254740991) — Messages opened at least once.
    - `clicked` (integer, required, min 0, max 9007199254740991) — Messages with a link clicked at least once.
    - `unsubscribed` (integer, required, min 0, max 9007199254740991) — Recipients who opted out through this campaign's link.
    - `total` (integer, required, min 0, max 9007199254740991) — All messages created.
  - `push` (CampaignMessageCounts, optional)
    - `queued` (integer, required, min 0, max 9007199254740991) — Messages waiting to be sent.
    - `sending` (integer, required, min 0, max 9007199254740991) — Messages being handed to the provider.
    - `skipped` (integer, required, min 0, max 9007199254740991) — Messages not sent; see `skippedByReason`.
    - `sent` (integer, required, min 0, max 9007199254740991) — Messages handed to the provider.
    - `failed` (integer, required, min 0, max 9007199254740991) — Messages that could not be sent.
    - `delivered` (integer, required, min 0, max 9007199254740991) — Messages confirmed delivered.
    - `bounced` (integer, required, min 0, max 9007199254740991) — Messages the recipient server rejected.
    - `complained` (integer, required, min 0, max 9007199254740991) — Messages the recipient marked as spam.
    - `opened` (integer, required, min 0, max 9007199254740991) — Messages opened at least once.
    - `clicked` (integer, required, min 0, max 9007199254740991) — Messages with a link clicked at least once.
    - `unsubscribed` (integer, required, min 0, max 9007199254740991) — Recipients who opted out through this campaign's link.
    - `total` (integer, required, min 0, max 9007199254740991) — All messages created.
- `push` (object | null, required) — Device-level outcomes. `null` when the campaign does not target push.
  - `pending` (integer, required, min 0, max 9007199254740991) — Devices not yet attempted.
  - `started` (integer, required, min 0, max 9007199254740991) — Devices being sent to now.
  - `accepted` (integer, required, min 0, max 9007199254740991) — Devices the push service accepted.
  - `invalid` (integer, required, min 0, max 9007199254740991) — Devices whose registration is no longer valid.
  - `rejected` (integer, required, min 0, max 9007199254740991) — Devices the push service permanently refused.
  - `retryable` (integer, required, min 0, max 9007199254740991) — Devices that failed temporarily and will be retried.
  - `unknown` (integer, required, min 0, max 9007199254740991) — Devices whose outcome could not be determined.
  - `skipped` (integer, required, min 0, max 9007199254740991) — Devices not sent to.
  - `total` (integer, required, min 0, max 9007199254740991) — All devices targeted.
  - `byPlatform` (object, required)
    - `ios` (object, optional)
      - `pending` (integer, required, min 0, max 9007199254740991) — Devices not yet attempted.
      - `started` (integer, required, min 0, max 9007199254740991) — Devices being sent to now.
      - `accepted` (integer, required, min 0, max 9007199254740991) — Devices the push service accepted.
      - `invalid` (integer, required, min 0, max 9007199254740991) — Devices whose registration is no longer valid.
      - `rejected` (integer, required, min 0, max 9007199254740991) — Devices the push service permanently refused.
      - `retryable` (integer, required, min 0, max 9007199254740991) — Devices that failed temporarily and will be retried.
      - `unknown` (integer, required, min 0, max 9007199254740991) — Devices whose outcome could not be determined.
      - `skipped` (integer, required, min 0, max 9007199254740991) — Devices not sent to.
      - `total` (integer, required, min 0, max 9007199254740991) — All devices targeted.
    - `android` (object, optional)
      - `pending` (integer, required, min 0, max 9007199254740991) — Devices not yet attempted.
      - `started` (integer, required, min 0, max 9007199254740991) — Devices being sent to now.
      - `accepted` (integer, required, min 0, max 9007199254740991) — Devices the push service accepted.
      - `invalid` (integer, required, min 0, max 9007199254740991) — Devices whose registration is no longer valid.
      - `rejected` (integer, required, min 0, max 9007199254740991) — Devices the push service permanently refused.
      - `retryable` (integer, required, min 0, max 9007199254740991) — Devices that failed temporarily and will be retried.
      - `unknown` (integer, required, min 0, max 9007199254740991) — Devices whose outcome could not be determined.
      - `skipped` (integer, required, min 0, max 9007199254740991) — Devices not sent to.
      - `total` (integer, required, min 0, max 9007199254740991) — All devices targeted.
    - `web` (object, optional)
      - `pending` (integer, required, min 0, max 9007199254740991) — Devices not yet attempted.
      - `started` (integer, required, min 0, max 9007199254740991) — Devices being sent to now.
      - `accepted` (integer, required, min 0, max 9007199254740991) — Devices the push service accepted.
      - `invalid` (integer, required, min 0, max 9007199254740991) — Devices whose registration is no longer valid.
      - `rejected` (integer, required, min 0, max 9007199254740991) — Devices the push service permanently refused.
      - `retryable` (integer, required, min 0, max 9007199254740991) — Devices that failed temporarily and will be retried.
      - `unknown` (integer, required, min 0, max 9007199254740991) — Devices whose outcome could not be determined.
      - `skipped` (integer, required, min 0, max 9007199254740991) — Devices not sent to.
      - `total` (integer, required, min 0, max 9007199254740991) — All devices targeted.
- `skippedByReason` (object, required) — Skipped messages by reason, such as `message_limit`; they sum to `skipped`.

## Example

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

Response `200`:

```json
{
  "data": {
    "campaignId": "018f2a4e-6b1c-7d3e-9f40-3478765e5a6b",
    "recipients": 0,
    "queued": 0,
    "sending": 0,
    "skipped": 0,
    "sent": 0,
    "failed": 0,
    "delivered": 0,
    "bounced": 0,
    "complained": 0,
    "opened": 0,
    "clicked": 0,
    "unsubscribed": 0,
    "total": 0,
    "byChannel": {},
    "push": {
      "pending": 0,
      "started": 0,
      "accepted": 0,
      "invalid": 0,
      "rejected": 0,
      "retryable": 0,
      "unknown": 0,
      "skipped": 0,
      "total": 0,
      "byPlatform": {}
    },
    "skippedByReason": {}
  }
}
```