---
title: "The full report"
method: GET
path: "/api/v1/campaigns/{id}/stats"
tags: ["Campaigns"]
---

# The full report

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

## Request

- Base URL: `https://mailcheer.com`
- URL: `https://mailcheer.com/api/v1/campaigns/{id}/stats`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Permission required: `campaigns:read`. Everything the Mailcheer campaign view shows, so you can display it in your own software: counters, rates (shares between 0 and 1, `null` as long as nothing has gone out), the curve of the first 48 hours in eight six-hour windows (empty if the campaign has not gone out), what people read on (top five rows, shares between 0 and 1, `proxiedShare` = the share of opens coming from a privacy relay such as Apple Mail or Gmail), links from most to least clicked, and the HTML as rendered at send time (empty string otherwise). Every figure comes twice: bots included (`opened`, `clicked` — as most tools count) and without bots (`humanOpened`, `humanClicked`), with `bots` saying how many were set aside and why. Open and click rates are calculated on delivered messages; delivery and bounce rates on recipients.

## Path parameters

- `id` string, required

## Response `200`

The report.

- CampaignStats
  - `campaign` object
    - `id` string
    - `name` string
    - `subject` string
    - `status` 'draft' | 'scheduled' | 'sending' | 'testing' | 'sent' | 'archived'
    - `kind` string
    - `fromName` string
    - `fromEmail` string
    - `sentAt` string, date-time, nullable
    - `scheduledAt` string, date-time, nullable
    - `updatedAt` string, date-time
  - `counts` object: A bot is an open or a click within two minutes of delivery (security gateways visit every link as the message arrives; privacy relays preload images), or one from a robot that declares itself in its user agent or comes from an address range its operator publishes (Google, Bing). Privacy relays (Apple Mail, Gmail, Yahoo) are not bots in themselves.
    - `recipients` integer
    - `delivered` integer
    - `opened` integer
    - `clicked` integer
    - `humanOpened` integer: Messages opened (or clicked) at least once by a person.
    - `humanClicked` integer: Messages clicked at least once by a person.
    - `bounced` integer
    - `complained` integer
    - `unsubscribed` integer: People who unsubscribed through this campaign's link (same definition as `recipients?status=unsubscribed`). An unsubscribe made through the API or in the app counts on no campaign.
    - `untracked` integer: Delivered messages that went out without an open-tracking pixel. Open rates are computed on the others; with none left, they are `null`.
  - `rates` object: Shares between 0 and 1; `null` as long as the denominator is empty.
    - `delivered` number, nullable
    - `opened` number, nullable
    - `clicked` number, nullable
    - `humanOpened` number, nullable: `opened` without bots, on delivered messages.
    - `humanClicked` number, nullable: `clicked` without bots, on delivered messages.
    - `bounced` number, nullable
  - `bots` object: Opens and clicks set aside as bots, counted as events (a gateway visiting three links counts three clicks), and why.
    - `opened` integer: Bot opens.
    - `clicked` integer: Bot clicks.
    - `delay` integer: Within two minutes of delivery.
    - `scanner` integer: A robot that declares itself, or an address its operator publishes.
  - `timeline` object[]: Eight six-hour windows from the send, `+0h` to `+42h`. Empty if the campaign has not gone out.
    - `label` string
    - `opened` integer
    - `clicked` integer
    - `humanOpened` integer: Opens by people in the window.
    - `humanClicked` integer: Clicks by people in the window.
  - `audience` object
    - `total` integer: Opens by people whose device is known (bot opens excluded).
    - `proxiedShare` number, nullable: Share of opens coming from a privacy relay (Apple Mail, Gmail): received, not necessarily read.
    - `device` object[]: Five rows at most, from the most to the least frequent.
      - `label` string
      - `count` integer
      - `share` number
    - `os` object[]: Five rows at most, from the most to the least frequent.
      - `label` string
      - `count` integer
      - `share` number
    - `client` object[]: Five rows at most, from the most to the least frequent.
      - `label` string
      - `count` integer
      - `share` number
  - `links` object[]: From most to least clicked, by people (bot clicks excluded).
    - `url` string
    - `clicks` integer
  - `html` string: The HTML as rendered at send time; empty string as long as it does not exist.

## Other responses

- `401`: Key missing, unknown or revoked.
- `403`: The key does not have the requested permission, or the workspace cannot send: `sending_blocked` (suspended, blocked or banned — nothing goes out, through any channel), `commitment_required` (the anti-spam commitment is not accepted), `reputation_blocked` (too many bounces or complaints).
- `404`: The object does not exist in this workspace.

---

[API](https://skmtc.dev/mailcheer/apis/mailcheer-api.md) · [All operations](https://skmtc.dev/mailcheer/apis/mailcheer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailcheer/apis/mailcheer-api/revisions/ba64b7ef2170?raw)