# Compare campaigns

`GET /v1/reports/campaigns`

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

One row per campaign with a marketing email sent, or a marketing push queued, in the window. Counts are send cohorts like the overview: email by the time it was sent, push by the time it was queued, and later feedback revises them. Conversions are those whose source message was sent in the window, and revenue is summed per goal currency, never converted. Rates are fractions; null means no denominator, and sorts below every rate. `firstSentAt` is the earliest send in the window, not the campaign schedule; `sent` sorts by email sent.

## Query parameters

- `limit` (integer, optional, min > 0, max 100, default `20`)
- `cursor` (string, optional, 1–2048 characters)
- `startDate` (string, optional, date) — First day, inclusive, in the workspace timezone. Give with `endDate`.
- `endDate` (string, optional, date) — Last day, inclusive, no later than today. Give with `startDate`; a window is at most 366 days. Omit both for the last 30 days.
- `sort` (string, optional, one of `firstSentAt`, `sent`, `openRate`, `clickRate`, `bounceRate`, `unsubscribeRate`, `conversions`, `-firstSentAt`, `-sent`, `-openRate`, `-clickRate`, `-bounceRate`, `-unsubscribeRate`, `-conversions`, default `"-firstSentAt"`) — A field ascending, or `-field` descending. Rates with no denominator sort last.

## Returns

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

- `campaignId` (string, required, uuid)
- `name` (string, required)
- `status` (string, required, one of `draft`, `scheduled`, `sending`, `sent`, `cancelled`)
- `channels` (string[], required) — The channels the campaign targets.
- `firstSentAt` (string, required, date-time) — The earliest send in the window, not the campaign schedule.
- `email` (object, required) — Email counts for the window.
  - `sent` (integer, required, min 0, max 9007199254740991)
  - `delivered` (integer, required, min 0, max 9007199254740991)
  - `opened` (integer, required, min 0, max 9007199254740991)
  - `clicked` (integer, required, min 0, max 9007199254740991)
  - `bounced` (integer, required, min 0, max 9007199254740991)
  - `complained` (integer, required, min 0, max 9007199254740991)
  - `unsubscribed` (integer, required, min 0, max 9007199254740991)
- `rates` (object, required) — Email rates as fractions; null when there is no denominator.
  - `delivery` (number | null, required, min 0)
  - `open` (number | null, required, min 0)
  - `click` (number | null, required, min 0)
  - `bounce` (number | null, required, min 0)
  - `complaint` (number | null, required, min 0)
  - `unsubscribe` (number | null, required, min 0)
- `push` (object, required) — Push counts for the window.
  - `sent` (integer, required, min 0, max 9007199254740991)
  - `failed` (integer, required, min 0, max 9007199254740991)
  - `opened` (integer, required, min 0, max 9007199254740991)
  - `clicked` (integer, required, min 0, max 9007199254740991)
- `conversions` (integer, required, min 0, max 9007199254740991) — Goal conversions whose source message was sent in the window.
- `revenue` (object[], required) — Revenue per goal currency.
  - `currency` (string | null, required) — The goal currency; null when it has none.
  - `value` (number, required) — Revenue in that currency, never converted.

## Example

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

Response `200`:

```json
{
  "data": [
    {
      "campaignId": "018f2a4e-6b1c-7d3e-9f40-3478765e5a6b",
      "name": "Weekend specials",
      "status": "draft",
      "channels": [
        "email"
      ],
      "firstSentAt": "2030-03-14T09:30:00Z",
      "email": {
        "sent": 0,
        "delivered": 0,
        "opened": 0,
        "clicked": 0,
        "bounced": 0,
        "complained": 0,
        "unsubscribed": 0
      },
      "rates": {
        "delivery": 0,
        "open": 0,
        "click": 0,
        "bounce": 0,
        "complaint": 0,
        "unsubscribe": 0
      },
      "push": {
        "sent": 0,
        "failed": 0,
        "opened": 0,
        "clicked": 0
      },
      "conversions": 0,
      "revenue": [
        {
          "currency": "USD",
          "value": 1
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "limit": 1,
      "nextCursor": "nextCursor_example"
    }
  }
}
```