# Retrieve the performance overview

`GET /v1/reports/overview`

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

Marketing email send cohorts, not event-occurrence totals, with marketing push in `push` and on each series row, by the day it was queued. The top-level counts, rates and health are email only; `allChannels` adds push to the sent, opened and clicked counts. Recent campaign counts are email only; `channels` says what each campaign targets. Later feedback revises cohorts. Bounce and complaint counts are durable first-occurrence facts, not current statuses. Health bands are local advisory thresholds, not SES account 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.

## Query parameters

- `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.

## Returns

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

- `generatedAt` (string, required, date-time)
- `timezone` (string, required) — The workspace timezone the dates and series days are in.
- `startDate` (string, required, date) — First day of the window (inclusive).
- `endDate` (string, required, date) — Last day of the window (inclusive).
- `scope` ("marketing_email", required) — What the top-level counts cover.
- `currentPeriod` (object, required) — The window as UTC instants.
  - `start` (string, required, date-time) — Start of the period (inclusive).
  - `end` (string, required, date-time) — End of the period (exclusive).
- `previousPeriod` (object, required) — The equal-length period just before it.
  - `start` (string, required, date-time) — Start of the period (inclusive).
  - `end` (string, required, date-time) — End of the period (exclusive).
- `current` (OverviewCounts, required) — Email counts in the window.
  - `sent` (integer, required, min -9007199254740991, max 9007199254740991)
  - `delivered` (integer, required, min -9007199254740991, max 9007199254740991)
  - `opened` (integer, required, min -9007199254740991, max 9007199254740991)
  - `clicked` (integer, required, min -9007199254740991, max 9007199254740991)
  - `feedbackObserved` (integer, required, min -9007199254740991, max 9007199254740991)
  - `bounced` (integer, required, min -9007199254740991, max 9007199254740991)
  - `complained` (integer, required, min -9007199254740991, max 9007199254740991)
  - `unsubscribed` (integer, required, min -9007199254740991, max 9007199254740991) — Recipients who opted out through the email's own link.
- `previous` (OverviewCounts, required) — Email counts in the previous period.
  - `sent` (integer, required, min -9007199254740991, max 9007199254740991)
  - `delivered` (integer, required, min -9007199254740991, max 9007199254740991)
  - `opened` (integer, required, min -9007199254740991, max 9007199254740991)
  - `clicked` (integer, required, min -9007199254740991, max 9007199254740991)
  - `feedbackObserved` (integer, required, min -9007199254740991, max 9007199254740991)
  - `bounced` (integer, required, min -9007199254740991, max 9007199254740991)
  - `complained` (integer, required, min -9007199254740991, max 9007199254740991)
  - `unsubscribed` (integer, required, min -9007199254740991, max 9007199254740991) — Recipients who opted out through the email's own link.
- `delta` (OverviewCounts, required) — `current` minus `previous`.
  - `sent` (integer, required, min -9007199254740991, max 9007199254740991)
  - `delivered` (integer, required, min -9007199254740991, max 9007199254740991)
  - `opened` (integer, required, min -9007199254740991, max 9007199254740991)
  - `clicked` (integer, required, min -9007199254740991, max 9007199254740991)
  - `feedbackObserved` (integer, required, min -9007199254740991, max 9007199254740991)
  - `bounced` (integer, required, min -9007199254740991, max 9007199254740991)
  - `complained` (integer, required, min -9007199254740991, max 9007199254740991)
  - `unsubscribed` (integer, required, min -9007199254740991, max 9007199254740991) — Recipients who opted out through the email's own link.
- `push` (object, required) — Marketing push counts, by the day it was queued.
  - `current` (object, required)
    - `sent` (integer, required, min -9007199254740991, max 9007199254740991)
    - `failed` (integer, required, min -9007199254740991, max 9007199254740991)
    - `opened` (integer, required, min -9007199254740991, max 9007199254740991)
    - `clicked` (integer, required, min -9007199254740991, max 9007199254740991)
  - `previous` (object, required)
    - `sent` (integer, required, min -9007199254740991, max 9007199254740991)
    - `failed` (integer, required, min -9007199254740991, max 9007199254740991)
    - `opened` (integer, required, min -9007199254740991, max 9007199254740991)
    - `clicked` (integer, required, min -9007199254740991, max 9007199254740991)
  - `delta` (object, required)
    - `sent` (integer, required, min -9007199254740991, max 9007199254740991)
    - `failed` (integer, required, min -9007199254740991, max 9007199254740991)
    - `opened` (integer, required, min -9007199254740991, max 9007199254740991)
    - `clicked` (integer, required, min -9007199254740991, max 9007199254740991)
- `allChannels` (object, required) — Marketing email and push together. Push has no delivery receipts, so there is no combined `delivered`.
  - `current` (object, required)
    - `sent` (integer, required, min -9007199254740991, max 9007199254740991)
    - `opened` (integer, required, min -9007199254740991, max 9007199254740991)
    - `clicked` (integer, required, min -9007199254740991, max 9007199254740991)
  - `previous` (object, required)
    - `sent` (integer, required, min -9007199254740991, max 9007199254740991)
    - `opened` (integer, required, min -9007199254740991, max 9007199254740991)
    - `clicked` (integer, required, min -9007199254740991, max 9007199254740991)
  - `delta` (object, required)
    - `sent` (integer, required, min -9007199254740991, max 9007199254740991)
    - `opened` (integer, required, min -9007199254740991, max 9007199254740991)
    - `clicked` (integer, required, min -9007199254740991, 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)
- `deliverabilityHealth` (object, required) — Advisory bounce and complaint health of marketing email.
  - `band` (string, required, one of `insufficient_data`, `healthy`, `watch`, `critical`) — `insufficient_data` until the sample and feedback coverage minimums are met.
  - `limits` (object, required) — Where the bands start: `watch` at the line where admins are warned, `critical` where marketing email pauses.
    - `watch` (object, required)
      - `bounceRatio` (number, required)
      - `complaintRatio` (number, required)
    - `critical` (object, required)
      - `bounceRatio` (number, required)
      - `complaintRatio` (number, required)
  - `sampleSize` (integer, required, min 0, max 9007199254740991) — Emails the band is judged on.
  - `minimumSampleSize` (100, required)
  - `feedbackCoverage` (number | null, required, min 0) — Fraction of the sample whose bounce or complaint outcome is known.
  - `minimumFeedbackCoverage` (0.95, required)
- `series` (object[], required, at most 366 items) — One entry per calendar day in the window.
  - `sent` (integer, required, min -9007199254740991, max 9007199254740991)
  - `delivered` (integer, required, min -9007199254740991, max 9007199254740991)
  - `opened` (integer, required, min -9007199254740991, max 9007199254740991)
  - `clicked` (integer, required, min -9007199254740991, max 9007199254740991)
  - `feedbackObserved` (integer, required, min -9007199254740991, max 9007199254740991)
  - `bounced` (integer, required, min -9007199254740991, max 9007199254740991)
  - `complained` (integer, required, min -9007199254740991, max 9007199254740991)
  - `unsubscribed` (integer, required, min -9007199254740991, max 9007199254740991) — Recipients who opted out through the email's own link.
  - `date` (string, required, date)
  - `push` (object, required)
    - `sent` (integer, required, min -9007199254740991, max 9007199254740991)
    - `failed` (integer, required, min -9007199254740991, max 9007199254740991)
    - `opened` (integer, required, min -9007199254740991, max 9007199254740991)
    - `clicked` (integer, required, min -9007199254740991, max 9007199254740991)
- `attention` (object, required) — Things that need a look.
  - `unverifiedDomainCount` (integer, required, min 0, max 9007199254740991) — Sending domains not yet verified.
  - `staleDraftCount` (integer, required, min 0, max 9007199254740991) — Drafts untouched for `staleAfterDays`.
  - `staleAfterDays` (7, required)
- `recentCampaigns` (object, required)
  - `hasMore` (boolean, required) — True when more campaigns exist than `items` lists.
  - `items` (object[], required, at most 5 items) — The newest campaigns with their email totals, counted in the background: every few minutes while a send is fresh, less often as it ages, and zeros until first counted.
    - `id` (string, required, uuid)
    - `name` (string, required)
    - `status` (string, required, one of `draft`, `scheduled`, `sending`, `sent`, `cancelled`)
    - `channels` (string[], required)
    - `createdAt` (string, required, date-time)
    - `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)
    - `openRate` (number | null, required, min 0)
    - `clickRate` (number | null, required, min 0)
- `conversions` (object, required) — Goal conversions by when they happened, all channels. 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, max 9007199254740991)
  - `previous` (integer, required, min 0, max 9007199254740991)
  - `revenue` (object[], required) — Revenue per goal currency.
    - `currency` (string | null, required) — The goal currency; null when none.
    - `current` (number, required)
    - `previous` (number, required)
- `liveJourneys` (object, required)
  - `hasMore` (boolean, required) — True when more live journeys exist than `items` lists.
  - `items` (object[], required, at most 5 items)
    - `id` (string, required, uuid)
    - `name` (string, required)
    - `triggerEvent` (string, required) — The event that enrols contacts.
    - `updatedAt` (string, required, date-time)

## Example

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

Response `200`:

```json
{
  "data": {
    "generatedAt": "2030-03-14T09:30:00Z",
    "timezone": "Europe/London",
    "startDate": "2030-03-14",
    "endDate": "2030-03-14",
    "scope": "marketing_email",
    "currentPeriod": {
      "start": "2030-03-14T09:30:00Z",
      "end": "2030-03-14T09:30:00Z"
    },
    "previousPeriod": {
      "start": "2030-03-14T09:30:00Z",
      "end": "2030-03-14T09:30:00Z"
    },
    "current": {
      "sent": -9007199254740991,
      "delivered": -9007199254740991,
      "opened": -9007199254740991,
      "clicked": -9007199254740991,
      "feedbackObserved": -9007199254740991,
      "bounced": -9007199254740991,
      "complained": -9007199254740991,
      "unsubscribed": -9007199254740991
    },
    "previous": {
      "sent": -9007199254740991,
      "delivered": -9007199254740991,
      "opened": -9007199254740991,
      "clicked": -9007199254740991,
      "feedbackObserved": -9007199254740991,
      "bounced": -9007199254740991,
      "complained": -9007199254740991,
      "unsubscribed": -9007199254740991
    },
    "delta": {
      "sent": -9007199254740991,
      "delivered": -9007199254740991,
      "opened": -9007199254740991,
      "clicked": -9007199254740991,
      "feedbackObserved": -9007199254740991,
      "bounced": -9007199254740991,
      "complained": -9007199254740991,
      "unsubscribed": -9007199254740991
    },
    "push": {
      "current": {
        "sent": -9007199254740991,
        "failed": -9007199254740991,
        "opened": -9007199254740991,
        "clicked": -9007199254740991
      },
      "previous": {
        "sent": -9007199254740991,
        "failed": -9007199254740991,
        "opened": -9007199254740991,
        "clicked": -9007199254740991
      },
      "delta": {
        "sent": -9007199254740991,
        "failed": -9007199254740991,
        "opened": -9007199254740991,
        "clicked": -9007199254740991
      }
    },
    "allChannels": {
      "current": {
        "sent": -9007199254740991,
        "opened": -9007199254740991,
        "clicked": -9007199254740991
      },
      "previous": {
        "sent": -9007199254740991,
        "opened": -9007199254740991,
        "clicked": -9007199254740991
      },
      "delta": {
        "sent": -9007199254740991,
        "opened": -9007199254740991,
        "clicked": -9007199254740991
      }
    },
    "rates": {
      "delivery": 0,
      "open": 0,
      "click": 0,
      "bounce": 0,
      "complaint": 0,
      "unsubscribe": 0
    },
    "deliverabilityHealth": {
      "band": "insufficient_data",
      "limits": {
        "watch": {
          "bounceRatio": 1,
          "complaintRatio": 1
        },
        "critical": {
          "bounceRatio": 1,
          "complaintRatio": 1
        }
      },
      "sampleSize": 0,
      "minimumSampleSize": 100,
      "feedbackCoverage": 0,
      "minimumFeedbackCoverage": 0.95
    },
    "series": [
      {
        "sent": -9007199254740991,
        "delivered": -9007199254740991,
        "opened": -9007199254740991,
        "clicked": -9007199254740991,
        "feedbackObserved": -9007199254740991,
        "bounced": -9007199254740991,
        "complained": -9007199254740991,
        "unsubscribed": -9007199254740991,
        "date": "2030-03-14",
        "push": {
          "sent": -9007199254740991,
          "failed": -9007199254740991,
          "opened": -9007199254740991,
          "clicked": -9007199254740991
        }
      }
    ],
    "attention": {
      "unverifiedDomainCount": 0,
      "staleDraftCount": 0,
      "staleAfterDays": 7
    },
    "recentCampaigns": {
      "hasMore": true,
      "items": [
        {
          "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
          "name": "Weekend specials",
          "status": "draft",
          "channels": [
            null
          ],
          "createdAt": "2030-03-14T09:30:00Z",
          "sent": 0,
          "delivered": 0,
          "opened": 0,
          "clicked": 0,
          "openRate": 0,
          "clickRate": 0
        }
      ]
    },
    "conversions": {
      "current": 0,
      "previous": 0,
      "revenue": [
        {
          "currency": "USD",
          "current": 1,
          "previous": 1
        }
      ]
    },
    "liveJourneys": {
      "hasMore": true,
      "items": [
        {
          "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
          "name": "Weekend specials",
          "triggerEvent": "triggerEvent_example",
          "updatedAt": "2030-03-14T09:30:00Z"
        }
      ]
    }
  }
}
```