---
title: "List broadcasts"
method: GET
path: "/v1/sites/{site_id}/broadcasts"
tags: ["Broadcasts"]
---

# List broadcasts

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

## Request

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

Broadcasts (e-mail campaigns) of the site in ascending order of id
(`order=newest` for the latest first), with
their status, e-mail subject, sender, audience, schedule, A/B test and folder.
Filters combine: every one given must match. `started_since` and
`started_before` select by when sending first started (`started_at`), so a
broadcast scheduled but not started yet is left out; `created_since` is when
it was created.

Nested lists keep their first 5 entries and texts their first 200 characters (links stay
whole); `truncated` names what was cut, `get_broadcast` has it whole. A page holds up to `limit` broadcasts; while
`next_cursor` is set, pass it as `cursor` for the next page. For the numbers
of a page of broadcasts call `get_broadcasts_stats_by_broadcast` with their
ids.

Deleted broadcasts are not listed. A broadcast without an e-mail is listed
with `email_id`, `subject`, `preview_text` and every field of `sender` null.

To keep a copy in sync, walk the whole list with the cursor and no filters
once. After that, pass `updated_since` set to the start of the previous walk
minus a margin of a few minutes, and merge by id. The margin is required:
a change may be stamped slightly earlier than it becomes visible.

`updated_at` moves with a change of the broadcast, a change of its status by
the user, the scheduler or the sender, the A/B result and a change or
deletion of the broadcast's e-mail, except a change by the support team.
It does not move with new statistics or a move to a folder. A deleted
broadcast simply disappears. Repeat the full walk now and then to notice all
of these.

## Path parameters

- `site_id` integer, required

## Query parameters

- `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
- `updated_since` string, date-time: `updated_at` at or after: changes of the broadcast and its e-mails, not new statistics or folder moves; deleted broadcasts are not listed; 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
- `cursor` string: `next_cursor` of the previous page, sent with the same `order`; omit for the first
- `limit` integer: Items per page
- `fields` string: Comma-separated fields to keep in each item, for example `id,name`; each item then carries only those fields and `id`. Omit for every field
- `order` 'oldest' | 'newest': Order of a list. oldest: the oldest item first; newest: the newest item first, for the latest items without paging through the history.

## Response `200`

Successful Response

- BroadcastPage: One page of a list; `next_cursor` is null on the last page.
  - `items` Broadcast[], required
    - `id` integer, required
    - `name` string, nullable: Name in the admin
    - `status` 'draft' | 'scheduled' | 'testing' | 'running' | 'paused' | 'stopped' | 'completed': draft: not scheduled or started yet. scheduled: waits for `schedule.scheduled_at`. testing: an A/B broadcast sending its variants to a test group or choosing the winner. running: being prepared or sending. paused: sending paused; it can be resumed. stopped: stopped before the end; it will not resume; to send it to those who did not get it, the user picks Resend > Resend to non-recipients on it in the admin. completed: sending finished.
    - `status_reason` 'ab_test' | 'completed' | 'scheduled' | 'no_recipients' | 'balance' | 'blocked_suspicious_activity' | 'blocked_poor_delivery' | 'sandbox' | 'not_on_plan' | 'failed' | 'paused_too_long' | 'stop_all' | 'deleted' | 'other': Why a status changed; null when a person simply made the change. While the site's sending is held, `diagnose_email_sending` names what holds it. ab_test: the A/B test finished or its winner was chosen. completed: every e-mail was sent. scheduled: started at the scheduled time. no_recipients: stopped because no contact matched the audience. balance: paused because the e-mail balance ran out. blocked_suspicious_activity: stopped because our automatic check for suspicious activity blocked the site's sending. blocked_poor_delivery: stopped because the site's sending was blocked: too many recipients bounced or complained. It stays blocked until the contact list is cleaned and support lifts the block. sandbox: stopped because sending is not enabled for the site yet or is paused pending a review. not_on_plan: paused because the site's plan no longer included broadcasts (a plan change, an ended trial or a suspended subscription). failed: stopped because it could not be prepared for sending. paused_too_long: stopped after being paused for over 30 days. stop_all: every broadcast of the site was paused or stopped at once. deleted: the broadcast was deleted, one entry per deletion: a preparing, running or paused broadcast is stopped by it (status stopped), any other keeps its status in the entry. other: another automatic change.
    - `email_id` integer, nullable: The broadcast's e-mail; null when it has none
    - `subject` string, nullable: Subject of the e-mail
    - `preview_text` string, nullable: Preview text of the e-mail, shown after the subject in inboxes
    - `sender` Sender, required
      - `name` string, nullable: The From display name; null when the e-mail has none
      - `address` string, nullable: The From address the e-mail goes out with: the one set in the editor when its domain is verified for the site, the default Getsitecontrol address otherwise
      - `reply_to` string, nullable: Where replies go; null when replies go to `address`
      - `domain` SenderDomain
        - `id` integer, required: Id in `list_email_domains`
        - `domain` string, required
        - `is_verified` boolean, required: true: e-mails go out from this domain; false: from the default address until it is verified
        - `state` 'verified' | 'not_started' | 'pending' | 'recheck_required', required: Where verification of the domain stands. `verified`: the records were found and emails go out from the domain. `not_started`: the domain has no records to publish yet, verification was never started. `pending`: the records are known but not found yet, either not published or not seen yet, and are checked again automatically. `recheck_required`: automatic checks gave up, two weeks after the domain was added.
    - `audience` Audience, required
      - `segments` SegmentRef[], required: Segments the audience conditions refer to
        - `id` integer, required: Segment id from `list_segments`
        - `name` string, nullable: null when the segment was deleted: then nobody receives it
      - `has_other_conditions` boolean, required: true: the conditions also hold rules besides segments; `get_broadcast` has them all
      - `limit` integer, nullable: At most this many recipients; null when not limited
      - `all_contacts` boolean, required: true: the conditions select every subscribed contact, the admin's All contacts; it is stored as an empty list of segments
    - `schedule` Schedule
      - `mode` 'immediate' | 'timezone' | 'smart' | 'ramp', required: immediate: sent right away, not spread over time. timezone: sent at `send_hours` of each recipient's local day. smart: spread over `send_period_hours` (2 to 24), each contact at the time it is most likely to engage, judged by its past activity. ramp: spread over `send_period_hours` (2 to 168) with a pace growing gradually, to protect the sender's reputation.
      - `scheduled_at` string, date-time, nullable: Scheduled start, with the offset of `timezone`; null when none is set
      - `timezone` string, nullable: IANA time zone the time was scheduled in
      - `send_hours` number[], nullable: Hours of the recipient's day to send at; `timezone` mode only
      - `send_period_hours` integer, nullable: Target hours the sending is spread over, not a promised end: the actual end follows the sender's pace, see `progress.finishes_at` of the broadcast's stats; `smart` and `ramp` modes only
    - `ab_test` ABTest, required
      - `is_enabled` boolean, required: Whether the broadcast tests e-mail variants on a part of the audience and sends the winner to the rest
      - `variant_email_ids` integer[], required: E-mail ids of the variants in their order; empty without A/B
      - `winner_email_id` integer, nullable: The winning variant; null until the winner is chosen
      - `winning_metric` 'open_rate' | 'click_rate' | 'other': open_rate: the variant with the highest open rate won. click_rate: the one with the highest click rate. other: chosen another way.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required: Last change of the broadcast, its status or its e-mail; see the list description; a move to another folder does not change it
    - `started_at` string, date-time, nullable: When sending first started; null until then
    - `ended_at` string, date-time, nullable: When the broadcast was stopped or completed; null until then
    - `launched_at` string, date-time, nullable: Latest start or scheduling by a person; null when there was none
    - `created_by` Author: A user of the account, as the admin shows them.
      - `id` integer, nullable: null for Support or for a user who was deleted
      - `name` string, nullable: null when the user has no name
      - `email` string, nullable: The user's sign-in e-mail; null for Support
    - `launched_by` Author: A user of the account, as the admin shows them.
      - `id` integer, nullable: null for Support or for a user who was deleted
      - `name` string, nullable: null when the user has no name
      - `email` string, nullable: The user's sign-in e-mail; null for Support
    - `edited_at` string, date-time, nullable: Last change made in the editor, to the broadcast or to one of its e-mails, A/B variants included
    - `edited_by` Author: A user of the account, as the admin shows them.
      - `id` integer, nullable: null for Support or for a user who was deleted
      - `name` string, nullable: null when the user has no name
      - `email` string, nullable: The user's sign-in e-mail; null for Support
    - `folder` Folder, required
      - `id` integer, required: 0 is General, where items outside any folder are
      - `name` string, required
    - `warnings` string[], required: Empty unless the broadcast could not be read in full; wording is not stable, do not parse
    - `truncated` string[]: Parts shortened in the list, as paths; the card has them whole. Empty when nothing was cut
  - `next_cursor` string, nullable

## 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
- `503`: Temporarily unavailable; retry later

---

[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)