---
title: "Broadcast statistics per broadcast"
method: GET
path: "/v1/sites/{site_id}/broadcasts/stats/by-broadcast"
tags: ["Broadcasts"]
---

# Broadcast statistics per broadcast

`GET /v1/sites/{site_id}/broadcasts/stats/by-broadcast`

## Request

- Base URL: `https://api.getsitecontrol.com`
- URL: `https://api.getsitecontrol.com/v1/sites/{site_id}/broadcasts/stats/by-broadcast`
- Auth: HTTP bearer

E-mail numbers per broadcast, in one of two ways.

With `broadcast_ids` (up to 100, from `list_broadcasts`): every
listed live broadcast of the site in the order given, zeros without e-mails;
repeated ids count once, unknown, deleted and foreign ids are left out. The
period is optional here: without `from` and `to` the numbers cover the whole
life, and `period` is null. This is how to get the numbers of a page of the
list in one call.

Without `broadcast_ids` the period is required: up to 100 live
broadcasts by `send`, most first, including those with activity but no
sending in the period. For the rest pass `broadcast_ids`. Deleted broadcasts
and e-mails without a broadcast are left out, so the sum may be below
`get_broadcasts_stats`.

`status`, `search`, `created_since`, `started_since`, `started_before` and
`folder_id` narrow either way to the broadcasts that match every one given,
and then every matched broadcast is listed, zero ones too: one call gives the
numbers of a folder, of the running broadcasts or of the broadcasts sent in a
month. `total` is the sum of the listed broadcasts; use it
rather than adding the items up.

Each number counts the events dated in the period on its own, so the numbers
are independent: a bounce or an open of an e-mail sent before the period
counts here too.

Every number counts e-mails, one e-mail being one message to one recipient,
and each e-mail at most once per metric: `send` e-mails sent, including those
rejected on sending; `bounce` e-mails that bounced or were rejected on
sending; `deliver` is `send` minus `bounce`, never below zero; `open` e-mails
opened; `click` e-mails with at least one link clicked; `unsubscribe` e-mails
whose recipient unsubscribed through them; `complaint` e-mails reported as
spam through the recipient's mail provider. `rates` next to each `total`
gives the delivery, open, click, click-to-open, unsubscribe, complaint and
bounce rates, rounded to 4 places; a rate is null when its denominator is 0,
as it is undefined, not zero.

## Path parameters

- `site_id` integer, required

## Query parameters

- `broadcast_ids` integer[]: Broadcast ids from `list_broadcasts`, up to 100; repeat for several. With them the period is optional
- `from` string, date: UTC day, included; omit for the whole life
- `to` string, date: UTC day, included; with `from`, today when omitted
- `status` BroadcastStatus[]: Only broadcasts in any of these statuses; repeat for several
- `search` string: Words of the name in order; case, spacing and punctuation are ignored. Or the exact id
- `created_since` string, date-time: Created at or after; without an offset, taken as UTC; a plain date means its start
- `started_since` string, date-time: Sending first started at or after this moment (started_at); without an offset, taken as UTC; a plain date means its start
- `started_before` string, date-time: Sending first started before this moment, excluded; without an offset, taken as UTC; a plain date means its start
- `folder_id` integer: Only the items of this folder, an id from `list_folders`; 0 is General

## Response `200`

Successful Response

- BroadcastStatsBreakdown
  - `period` StatsPeriod
    - `date_from` string, date, required: First day, UTC, included
    - `date_to` string, date, required: Last day, UTC, included
  - `matched` integer, nullable: How many live broadcasts the filters or ids matched; null without them. 0 means nothing matched, not that nothing happened: check the filters or ids
  - `total` EmailMetrics, required: E-mail counts; every key is always present. `open`, `click` and the rest count each e-mail once. `send` includes e-mails rejected on sending, which are also counted in `bounce`. `complaint` is spam complaints reported by mail providers. For a period, each number counts the events dated in it, so the numbers are independent: a bounce may fall in a later period than its sending. `deliver` is `send` minus `bounce`, never below zero.
    - `send` integer, required
    - `deliver` integer, required
    - `bounce` integer, required
    - `open` integer, required
    - `click` integer, required
    - `unsubscribe` integer, required
    - `complaint` integer, required
  - `rates` EmailRates, required: Rates from `total`, each a fraction rounded to 4 places: 0.0125 is 1.25%. For a period, each counter counts the events dated in it, so an open or a bounce of an e-mail sent before the period counts while its sending does not, and a rate can exceed 1.
    - `deliver` number, nullable: Delivery rate: `deliver` / `send`; null when `send` is 0: the rate is undefined, not zero
    - `open` number, nullable: Open rate: `open` / `deliver`; null when `deliver` is 0: the rate is undefined, not zero
    - `click` number, nullable: Click rate: `click` / `deliver`; null when `deliver` is 0: the rate is undefined, not zero
    - `click_to_open` number, nullable: Click-to-open rate: `click` / `open`; null when `open` is 0: the rate is undefined, not zero. A click is counted without an open when the recipient's mail app does not load images, so it can exceed 1
    - `unsubscribe` number, nullable: Unsubscribe rate: `unsubscribe` / `deliver`; null when `deliver` is 0: the rate is undefined, not zero
    - `complaint` number, nullable: Spam complaint rate: `complaint` / `deliver`; null when `deliver` is 0: the rate is undefined, not zero
    - `bounce` number, nullable: Bounce rate: `bounce` / `send`; null when `send` is 0: the rate is undefined, not zero
  - `items` BroadcastStatsBreakdownItem[], required
    - `id` integer, required: Broadcast id
    - `name` string, nullable: Broadcast name
    - `total` EmailMetrics, required: E-mail counts; every key is always present. `open`, `click` and the rest count each e-mail once. `send` includes e-mails rejected on sending, which are also counted in `bounce`. `complaint` is spam complaints reported by mail providers. For a period, each number counts the events dated in it, so the numbers are independent: a bounce may fall in a later period than its sending. `deliver` is `send` minus `bounce`, never below zero.
      - `send` integer, required
      - `deliver` integer, required
      - `bounce` integer, required
      - `open` integer, required
      - `click` integer, required
      - `unsubscribe` integer, required
      - `complaint` integer, required
    - `rates` EmailRates, required: Rates from `total`, each a fraction rounded to 4 places: 0.0125 is 1.25%. For a period, each counter counts the events dated in it, so an open or a bounce of an e-mail sent before the period counts while its sending does not, and a rate can exceed 1.
      - `deliver` number, nullable: Delivery rate: `deliver` / `send`; null when `send` is 0: the rate is undefined, not zero
      - `open` number, nullable: Open rate: `open` / `deliver`; null when `deliver` is 0: the rate is undefined, not zero
      - `click` number, nullable: Click rate: `click` / `deliver`; null when `deliver` is 0: the rate is undefined, not zero
      - `click_to_open` number, nullable: Click-to-open rate: `click` / `open`; null when `open` is 0: the rate is undefined, not zero. A click is counted without an open when the recipient's mail app does not load images, so it can exceed 1
      - `unsubscribe` number, nullable: Unsubscribe rate: `unsubscribe` / `deliver`; null when `deliver` is 0: the rate is undefined, not zero
      - `complaint` number, nullable: Spam complaint rate: `complaint` / `deliver`; null when `deliver` is 0: the rate is undefined, not zero
      - `bounce` number, nullable: Bounce rate: `bounce` / `send`; null when `send` is 0: the rate is undefined, not zero

## Other responses

- `400`: Unsupported GSC-Version
- `401`: Missing or invalid API key or access token
- `403`: Access denied
- `404`: Not found
- `422`: Validation failed
- `429`: `rate_limited`: a limit of the key or the account is spent; statistics also spend the heavy request limit of the key. Retry after `Retry-After` seconds
- `503`: `temporarily_unavailable`: the numbers took too long to count or the limits cannot be checked right now; retry later or shorten the period

---

[API](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api.md) - [All operations](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api/revisions/084fcad80e75?raw)