# Retrieve a campaign's email results by domain, device or country

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

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

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

Works with integration, agent and partner keys.

Splits a campaign's email results into rows by the recipient's email domain (`gmail.com`), the device they first opened or clicked on (`desktop`, `mobile`, `tablet`), or the contact's country (`GB`), counted the same way as the campaign's metrics. Use it to find where a problem sits: bounces concentrated on one domain point at that mailbox provider, not at the whole list.

Rows are ordered by messages sent, largest first. The 50 largest are listed, and everything past them is summed in `other` (null when there are none). A row's `key` is `null` when the value is unknown: a device is known only once a person opens with images on or clicks (machine opens, such as Apple Mail Privacy Protection's and Gmail's prefetch, and Gmail's image proxy name no device, and other image proxies may read as desktop); a country only when the contact has one; a domain only while the message still names someone (not after the contact is deleted).

Push results are not included: a push campaign's per-device outcomes are in its metrics, under `push.devices`.

## Path parameters

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

## Query parameters

- `groupBy` (string, required, one of `domain`, `device`, `country`) — `domain`: the recipient's email domain. `device`: the kind of device a person first opened or clicked on. `country`: the contact's country (ISO 3166-1 alpha-2).

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

- `campaignId` (string, required, uuid)
- `groupBy` (string, required, one of `domain`, `device`, `country`) — `domain`: the recipient's email domain. `device`: the kind of device a person first opened or clicked on. `country`: the contact's country (ISO 3166-1 alpha-2).
- `rows` (object[], required, at most 50 items) — The largest rows by messages sent, largest first.
  - `sent` (integer, required, min 0)
  - `delivered` (integer, required, min 0)
  - `opened` (integer, required, min 0) — Including machine opens, as in the campaign's metrics.
  - `openedByMachine` (integer, required, min 0)
  - `clicked` (integer, required, min 0)
  - `clickedByMachine` (integer, required, min 0)
  - `bounced` (integer, required, min 0)
  - `complained` (integer, required, min 0)
  - `unsubscribed` (integer, required, min 0)
  - `key` (string | null, required) — The domain, `desktop` / `mobile` / `tablet`, or a country code; `null` when unknown.
- `other` (object | null, required) — Every row past the largest 50, summed; `null` when there are 50 or fewer.
  - `sent` (integer, required, min 0)
  - `delivered` (integer, required, min 0)
  - `opened` (integer, required, min 0) — Including machine opens, as in the campaign's metrics.
  - `openedByMachine` (integer, required, min 0)
  - `clicked` (integer, required, min 0)
  - `clickedByMachine` (integer, required, min 0)
  - `bounced` (integer, required, min 0)
  - `complained` (integer, required, min 0)
  - `unsubscribed` (integer, required, min 0)

## Example

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

Response `200`:

```json
{
  "data": {
    "campaignId": "0192f3d3-5e6f-7071-8c83-9e0f1a2b3c4d",
    "groupBy": "domain",
    "rows": [
      {
        "key": "gmail.com",
        "sent": 1320,
        "delivered": 1302,
        "opened": 540,
        "openedByMachine": 0,
        "clicked": 151,
        "clickedByMachine": 12,
        "bounced": 18,
        "complained": 1,
        "unsubscribed": 2
      },
      {
        "key": "icloud.com",
        "sent": 410,
        "delivered": 405,
        "opened": 371,
        "openedByMachine": 322,
        "clicked": 38,
        "clickedByMachine": 2,
        "bounced": 5,
        "complained": 0,
        "unsubscribed": 1
      }
    ],
    "other": null
  }
}
```