# Retrieve the performance overview

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

`GET /v1/reports/overview`

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

Works with integration, agent and partner keys.

Returns how the workspace did in a window: marketing email in `email` and marketing push in `push`, never added together, each against the period before. Email counts are send cohorts (by the day it was sent), push by the day it was queued, and later feedback revises them. Bounce and complaint counts are durable first-occurrence facts, not current statuses. `conversions` are the goal conversions a message drove, with their credited revenue, gross; `refunds` sums every refund in the window beside it. `deliverabilityHealth` is an advisory band from the workspace's own bounce and complaint rates against Kirora's warning and pause lines, not the sending provider's reputation. Rates are fractions; null means no denominator. Days are calendar days in the workspace timezone (`timezone`, set in workspace settings); the first and last may be partial. Without `from` and `to`, the window is the last 30 days ending today.

## Query parameters

- `from` (string, optional) — Start of the window, inclusive: a date-time, or a date meaning the start of that day in the workspace timezone. Give with `to`; omit both for the last 30 days.
- `to` (string, optional) — End of the window, exclusive, in the same forms. To include a whole last day, pass the day after it: `from=2026-10-01&to=2026-10-08` covers 1 to 7 October. No later than the end of today; a window touches at most 366 days. Give with `from`.
- `tag` (string, optional, 1–64 characters) — Only email, push and conversions from campaigns and journeys carrying this tag, its name matched without case: "how did everything tagged Black Friday do". Refunds are not filtered: no message is linked to them.

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

- `generatedAt` (string, required, date-time)
- `timezone` (string, required) — The workspace timezone that date bounds and series days are in.
- `from` (string, required, date-time) — Start of the window, inclusive.
- `to` (string, required, date-time) — End of the window, exclusive.
- `previousPeriod` (object, required) — The equal-length period just before the window.
  - `from` (string, required, date-time) — Start of the window, inclusive.
  - `to` (string, required, date-time) — End of the window, exclusive.
- `email` (object, required) — Marketing email from campaigns and journeys, by the day it was sent; `failed` and `skipped` email that never reached the provider counts on the day it was queued. `sent` covers only email the provider accepted.
  - `current` (OverviewCounts, required) — Counts in the window.
    - `sent` (integer, required)
    - `delivered` (integer, required)
    - `opened` (integer, required) — Opened at least once, including `openedByMachine`: the open rate counts those too.
    - `openedByMachine` (integer, required) — Of `opened`, those only a machine opened: a mail app fetched its images with no reader (Apple Mail Privacy Protection, Gmail's prefetch on delivery) or a mail security scanner checked it.
    - `clicked` (integer, required) — With a link clicked by a person.
    - `simulated` (integer, required, min 0) — Of `sent`, test sends whose outcome was acted out: those to `delivered@`, `bounce@` or `complaint@example.com` (the transactional guide's "Test addresses"). Counted in `sent` and `delivered`; never in `bounced`, `complained`, `feedbackObserved`, the bounce and complaint rates or `deliverabilityHealth`.
    - `feedbackObserved` (integer, required) — Of the real sends in `sent`, those whose delivery, bounce or complaint is known.
    - `failed` (integer, required) — Not delivered, with no bounce or complaint: refused before sending (counted on the day it was queued) or failed after it (on the day it was sent, and also in `sent`). `failure.reason` on each message says why.
    - `failedBeforeSending` (integer, required) — Of `failed`, those refused before reaching the provider, on the day they were queued. Not in `sent`, like `skipped`, so `sent + failedBeforeSending + skipped` counts each message once.
    - `skipped` (integer, required) — Stopped before sending by a guard (no consent, suppressed, no address), on the day it was queued. Not in `sent`.
    - `bounced` (integer, required)
    - `complained` (integer, required)
    - `unsubscribed` (integer, required) — Recipients who opted out through the email's own link.
  - `previous` (OverviewCounts, required) — Counts in the previous period.
    - `sent` (integer, required)
    - `delivered` (integer, required)
    - `opened` (integer, required) — Opened at least once, including `openedByMachine`: the open rate counts those too.
    - `openedByMachine` (integer, required) — Of `opened`, those only a machine opened: a mail app fetched its images with no reader (Apple Mail Privacy Protection, Gmail's prefetch on delivery) or a mail security scanner checked it.
    - `clicked` (integer, required) — With a link clicked by a person.
    - `simulated` (integer, required, min 0) — Of `sent`, test sends whose outcome was acted out: those to `delivered@`, `bounce@` or `complaint@example.com` (the transactional guide's "Test addresses"). Counted in `sent` and `delivered`; never in `bounced`, `complained`, `feedbackObserved`, the bounce and complaint rates or `deliverabilityHealth`.
    - `feedbackObserved` (integer, required) — Of the real sends in `sent`, those whose delivery, bounce or complaint is known.
    - `failed` (integer, required) — Not delivered, with no bounce or complaint: refused before sending (counted on the day it was queued) or failed after it (on the day it was sent, and also in `sent`). `failure.reason` on each message says why.
    - `failedBeforeSending` (integer, required) — Of `failed`, those refused before reaching the provider, on the day they were queued. Not in `sent`, like `skipped`, so `sent + failedBeforeSending + skipped` counts each message once.
    - `skipped` (integer, required) — Stopped before sending by a guard (no consent, suppressed, no address), on the day it was queued. Not in `sent`.
    - `bounced` (integer, required)
    - `complained` (integer, required)
    - `unsubscribed` (integer, required) — Recipients who opted out through the email's own link.
  - `delta` (OverviewCounts, required) — `current` minus `previous`.
    - `sent` (integer, required)
    - `delivered` (integer, required)
    - `opened` (integer, required) — Opened at least once, including `openedByMachine`: the open rate counts those too.
    - `openedByMachine` (integer, required) — Of `opened`, those only a machine opened: a mail app fetched its images with no reader (Apple Mail Privacy Protection, Gmail's prefetch on delivery) or a mail security scanner checked it.
    - `clicked` (integer, required) — With a link clicked by a person.
    - `simulated` (integer, required, min 0) — Of `sent`, test sends whose outcome was acted out: those to `delivered@`, `bounce@` or `complaint@example.com` (the transactional guide's "Test addresses"). Counted in `sent` and `delivered`; never in `bounced`, `complained`, `feedbackObserved`, the bounce and complaint rates or `deliverabilityHealth`.
    - `feedbackObserved` (integer, required) — Of the real sends in `sent`, those whose delivery, bounce or complaint is known.
    - `failed` (integer, required) — Not delivered, with no bounce or complaint: refused before sending (counted on the day it was queued) or failed after it (on the day it was sent, and also in `sent`). `failure.reason` on each message says why.
    - `failedBeforeSending` (integer, required) — Of `failed`, those refused before reaching the provider, on the day they were queued. Not in `sent`, like `skipped`, so `sent + failedBeforeSending + skipped` counts each message once.
    - `skipped` (integer, required) — Stopped before sending by a guard (no consent, suppressed, no address), on the day it was queued. Not in `sent`.
    - `bounced` (integer, required)
    - `complained` (integer, required)
    - `unsubscribed` (integer, required) — Recipients who opted out through the email's own link.
  - `rates` (EmailRates, required) — Email rates as fractions: delivery over sent; bounce and complaint over real sends (`sent` less `simulated` where the counts give it), as `deliverabilityHealth` judges them; open, click and unsubscribe over delivered. `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) — Marketing push, by the day it was queued.
  - `current` (OverviewPushCounts, required)
    - `sent` (integer, required)
    - `failed` (integer, required)
    - `opened` (integer, required)
    - `clicked` (integer, required)
  - `previous` (OverviewPushCounts, required)
    - `sent` (integer, required)
    - `failed` (integer, required)
    - `opened` (integer, required)
    - `clicked` (integer, required)
  - `delta` (OverviewPushCounts, required)
    - `sent` (integer, required)
    - `failed` (integer, required)
    - `opened` (integer, required)
    - `clicked` (integer, required)
- `conversions` (object, required) — Goal conversions a message drove, by when they happened, from email and push alike: a conversion is one order, whichever message gets the credit. An event credited to several campaigns' or journeys' goals counts once here, though each goal's own report counts it. Revenue is summed per goal currency and never converted; goals without a currency share the null row.
  - `current` (integer, required, min 0)
  - `previous` (integer, required, min 0)
  - `revenue` (object[], required) — Credited revenue per goal currency, gross: before refunds.
    - `currency` (string | null, required) — The goal currency; null when none.
    - `current` (number, required)
    - `previous` (number, required)
  - `revenueWithheld` (boolean, required) — True when `revenue` leaves out the value of goals whose value property is a masked attribute this viewer may not see: their conversions are counted, their values are not, here and in each day's `revenue`.
- `refunds` (Money[], required) — All refunds in the window, whether or not a message drove the order: the `total` of each `Order Refunded` event (or the workspace's own refund event, set in its key events), per its `currency`, never converted. Not subtracted from `conversions.revenue`. Empty when `refundsWithheld`.
  - `currency` (string | null, required) — The currency, an ISO 4217 code; null when none was named.
  - `value` (number, required) — The amount in that currency.
- `refundsWithheld` (boolean, required) — True when `refunds` is left out because `total` or `currency` is a masked attribute this viewer may not see.
- `deliverabilityHealth` (DeliverabilityHealth, required) — Advisory bounce and complaint health on the workspace's lines (`limits`): judged once `sampleSize` and `feedbackCoverage` reach their minimums. Bounces and complaints are recorded ones, so a simulated test bounce never counts.
  - `band` (string, required, one of `insufficient_data`, `healthy`, `watch`, `critical`) — `insufficient_data` until the sample and feedback coverage minimums are met; then the highest line the bounce or complaint ratio reaches.
  - `limits` (DeliverabilityLimits, required) — Where the bands start, the workspace's own lines: `watch` where its admins are warned, `critical` where its marketing email pauses. The pause is judged on all of the workspace's marketing email over the last 24 hours (or week, for a small sender), not on one report.
    - `watch` (object, required)
      - `bounceRatio` (number, required, min 0, max 1) — A ratio from 0 to 1: 0.05 is 5%.
      - `complaintRatio` (number, required, min 0, max 1) — A ratio from 0 to 1: 0.05 is 5%.
    - `critical` (object, required)
      - `bounceRatio` (number, required, min 0, max 1) — A ratio from 0 to 1: 0.05 is 5%.
      - `complaintRatio` (number, required, min 0, max 1) — A ratio from 0 to 1: 0.05 is 5%.
  - `bounceRatio` (number | null, required, min 0, max 1) — Recorded bounces per sent email, the figure the band compares with `limits`; `null` while `sampleSize` is 0.
  - `complaintRatio` (number | null, required, min 0, max 1) — Recorded complaints per sent email, the figure the band compares with `limits`; `null` while `sampleSize` is 0.
  - `sampleSize` (integer, required, min 0) — Sent emails the band is judged on: real sends only, with test sends that act an outcome out (`delivered@`, `bounce@`, `complaint@example.com`) left out.
  - `minimumSampleSize` (integer, required, min 1) — The fewest emails (`sampleSize`) the band is judged on, currently 100: below it the band is `insufficient_data`.
  - `feedbackCoverage` (number | null, required, min 0, max 1) — Share of the sample whose outcome (delivered, bounced or complained) is known; `null` before any email is sent.
  - `minimumFeedbackCoverage` (number, required, min 0, max 1) — The least `feedbackCoverage` the band is judged on, currently 0.95: below it the band is `insufficient_data`, as bounce and complaint reports are still arriving.
- `series` (object[], required, at most 366 items) — One point per calendar day in the window: email and push by the day they were sent, conversions and revenue by the day they happened.
  - `startsAt` (string, required, date-time) — When this day starts in `timezone`, given as an instant.
  - `email` (OverviewCounts, required) — Email by the day it was sent; email never sent by the day it was queued.
    - `sent` (integer, required)
    - `delivered` (integer, required)
    - `opened` (integer, required) — Opened at least once, including `openedByMachine`: the open rate counts those too.
    - `openedByMachine` (integer, required) — Of `opened`, those only a machine opened: a mail app fetched its images with no reader (Apple Mail Privacy Protection, Gmail's prefetch on delivery) or a mail security scanner checked it.
    - `clicked` (integer, required) — With a link clicked by a person.
    - `simulated` (integer, required, min 0) — Of `sent`, test sends whose outcome was acted out: those to `delivered@`, `bounce@` or `complaint@example.com` (the transactional guide's "Test addresses"). Counted in `sent` and `delivered`; never in `bounced`, `complained`, `feedbackObserved`, the bounce and complaint rates or `deliverabilityHealth`.
    - `feedbackObserved` (integer, required) — Of the real sends in `sent`, those whose delivery, bounce or complaint is known.
    - `failed` (integer, required) — Not delivered, with no bounce or complaint: refused before sending (counted on the day it was queued) or failed after it (on the day it was sent, and also in `sent`). `failure.reason` on each message says why.
    - `failedBeforeSending` (integer, required) — Of `failed`, those refused before reaching the provider, on the day they were queued. Not in `sent`, like `skipped`, so `sent + failedBeforeSending + skipped` counts each message once.
    - `skipped` (integer, required) — Stopped before sending by a guard (no consent, suppressed, no address), on the day it was queued. Not in `sent`.
    - `bounced` (integer, required)
    - `complained` (integer, required)
    - `unsubscribed` (integer, required) — Recipients who opted out through the email's own link.
  - `push` (OverviewPushCounts, required) — Push by the day it was queued.
    - `sent` (integer, required)
    - `failed` (integer, required)
    - `opened` (integer, required)
    - `clicked` (integer, required)
  - `conversions` (integer, required, min 0) — Goal conversions that happened that day, as in `conversions`.
  - `revenue` (Money[], required) — Credited revenue that day per goal currency, never converted; empty when none.
    - `currency` (string | null, required) — The currency, an ISO 4217 code; null when none was named.
    - `value` (number, required) — The amount in that currency.

## Example

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

Response `200`:

```json
{
  "data": {
    "generatedAt": "2026-10-08T12:00:00.000Z",
    "timezone": "Europe/London",
    "from": "2026-09-30T23:00:00.000Z",
    "to": "2026-10-07T23:00:00.000Z",
    "previousPeriod": {
      "from": "2026-09-23T23:00:00.000Z",
      "to": "2026-09-30T23:00:00.000Z"
    },
    "email": {
      "current": {
        "sent": 4000,
        "delivered": 3920,
        "opened": 1640,
        "openedByMachine": 480,
        "clicked": 384,
        "simulated": 0,
        "feedbackObserved": 4000,
        "failed": 12,
        "failedBeforeSending": 8,
        "skipped": 80,
        "bounced": 48,
        "complained": 4,
        "unsubscribed": 24
      },
      "previous": {
        "sent": 3000,
        "delivered": 2940,
        "opened": 1230,
        "openedByMachine": 360,
        "clicked": 288,
        "simulated": 0,
        "feedbackObserved": 3000,
        "failed": 9,
        "failedBeforeSending": 6,
        "skipped": 60,
        "bounced": 36,
        "complained": 3,
        "unsubscribed": 18
      },
      "delta": {
        "sent": 1000,
        "delivered": 980,
        "opened": 410,
        "openedByMachine": 120,
        "clicked": 96,
        "simulated": 0,
        "feedbackObserved": 1000,
        "failed": 3,
        "failedBeforeSending": 2,
        "skipped": 20,
        "bounced": 12,
        "complained": 1,
        "unsubscribed": 6
      },
      "rates": {
        "delivery": 0.98,
        "open": 0.41,
        "click": 0.096,
        "bounce": 0.012,
        "complaint": 0.001,
        "unsubscribe": 0.006
      }
    },
    "push": {
      "current": {
        "sent": 1200,
        "failed": 16,
        "opened": 208,
        "clicked": 72
      },
      "previous": {
        "sent": 900,
        "failed": 12,
        "opened": 156,
        "clicked": 54
      },
      "delta": {
        "sent": 300,
        "failed": 4,
        "opened": 52,
        "clicked": 18
      }
    },
    "conversions": {
      "current": 37,
      "previous": 29,
      "revenue": [
        {
          "currency": "USD",
          "current": 1720.5,
          "previous": 1304
        }
      ],
      "revenueWithheld": false
    },
    "refunds": [
      {
        "currency": "USD",
        "value": 120
      }
    ],
    "refundsWithheld": false,
    "deliverabilityHealth": {
      "band": "healthy",
      "limits": {
        "watch": {
          "bounceRatio": 0.02,
          "complaintRatio": 0.0005
        },
        "critical": {
          "bounceRatio": 0.03,
          "complaintRatio": 0.0008
        }
      },
      "bounceRatio": 0.012,
      "complaintRatio": 0.00025,
      "sampleSize": 4000,
      "minimumSampleSize": 100,
      "feedbackCoverage": 1,
      "minimumFeedbackCoverage": 0.95
    },
    "series": [
      {
        "startsAt": "2026-09-30T23:00:00.000Z",
        "email": {
          "sent": 1000,
          "delivered": 980,
          "opened": 410,
          "openedByMachine": 120,
          "clicked": 96,
          "simulated": 0,
          "feedbackObserved": 1000,
          "failed": 3,
          "failedBeforeSending": 2,
          "skipped": 20,
          "bounced": 12,
          "complained": 1,
          "unsubscribed": 6
        },
        "push": {
          "sent": 300,
          "failed": 4,
          "opened": 52,
          "clicked": 18
        },
        "conversions": 5,
        "revenue": [
          {
            "currency": "USD",
            "value": 412.5
          }
        ]
      },
      {
        "startsAt": "2026-10-01T23:00:00.000Z",
        "email": {
          "sent": 1000,
          "delivered": 980,
          "opened": 410,
          "openedByMachine": 120,
          "clicked": 96,
          "simulated": 0,
          "feedbackObserved": 1000,
          "failed": 3,
          "failedBeforeSending": 2,
          "skipped": 20,
          "bounced": 12,
          "complained": 1,
          "unsubscribed": 6
        },
        "push": {
          "sent": 300,
          "failed": 4,
          "opened": 52,
          "clicked": 18
        },
        "conversions": 0,
        "revenue": []
      }
    ]
  }
}
```