---
title: "Site broadcast statistics over time"
method: GET
path: "/v1/sites/{site_id}/broadcasts/stats/timeline"
tags: ["Broadcasts"]
---

# Site broadcast statistics over time

`GET /v1/sites/{site_id}/broadcasts/stats/timeline`

## Request

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

E-mail numbers of all broadcasts of the site, without filters deleted ones
included, split into buckets of `interval`. `broadcast_ids`, `status`, `search`, `created_since`, `started_since`,
`started_before` and `folder_id` narrow the count to the live broadcasts that
match every one given; `matched` says how many, and `matched: 0` means no
broadcast matched. Buckets are consecutive days, calendar weeks (Monday to Sunday) or calendar
months; the first and the last are cut to the period. Every bucket is
present, an empty one with zeros.

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

- `interval` 'day' | 'week' | 'month': day, calendar week (Monday to Sunday) or calendar month.
- `from` string, date, required: First day of the period, UTC, included
- `to` string, date: Last day of the period, UTC, included; today when omitted
- `broadcast_ids` integer[]: Only these broadcast ids from `list_broadcasts`, up to 100; repeat for several
- `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

- EmailStatsTimeline
  - `period` StatsPeriod, required
    - `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
  - `interval` 'day' | 'week' | 'month', required: day, calendar week (Monday to Sunday) or calendar month.
  - `items` EmailStatsBucket[], required: Every bucket of the period in order, empty ones with zeros
    - `date_from` string, date, required
    - `date_to` string, date, required
    - `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)