---
title: "Get a broadcast"
method: GET
path: "/v1/sites/{site_id}/broadcasts/{broadcast_id}"
tags: ["Broadcasts"]
---

# Get a broadcast

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

## Request

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

One broadcast with the fields of `list_broadcasts`, nothing shortened, plus
its whole audience: the condition tree and the recipient settings (limit,
sort, quality gate), the A/B test split and duration, and whether links get
UTM parameters. How many contacts it reaches is `get_broadcast_recipients`,
its numbers are in `get_broadcast_stats`, its clicks by link in
`get_broadcast_clicks`, the body of its e-mail in `get_email`.

## Path parameters

- `site_id` integer, required
- `broadcast_id` integer, required: Broadcast id from `list_broadcasts`

## Response `200`

Successful Response

- BroadcastCard
  - `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` AudienceCard, 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
    - `conditions` object, nullable: Who receives the broadcast. Only subscribed contacts are sent to: that condition is always added and is not in the tree. The tree is written as segment conditions. Which contacts belong to the segment: a tree of conditions, applied to the contacts as they are at the moment it is used. Conditions are the condition language of the Getsitecontrol admin, with its own variable names and codes; they are not the field names and values of `Contact`. A segment written here can be edited in the admin, and the variables below are the ones the admin's condition editor offers. A node is an object with exactly `op` and `args`. A group has `op` `and` or `or` and nodes in `args`; a leaf has the variable `{{$contact.<name>}}` as the first argument, then its values: none for `*` (is set) and `undefined` (is not set), two for `between` and `!between`, one for the rest. To negate, use the opposite operator; there is no `not` node. The admin editor shows a root group whose `args` are groups, each holding leaves, as in the example; write that shape so the segment stays editable there. `{"op": "and", "args": []}` matches every contact of the site. Conditions are saved as sent. Values are integers, strings or, for `ina` and `!ina`, a list of them. | Operator | Meaning | |---|---| | `=`, `!=` | equals, differs | | `ina`, `!ina` | any of the list, none of it | | `<`, `>`, `between`, `!between` | compare; `between` includes both ends | | `^`, `$`, `in`, `match` (and `!`-forms) | starts with, ends with, contains, wildcard `*` without case | | `*`, `undefined` | is set, is not set | Text operators other than `match` are case sensitive, except on `$contact.email`: a contact's email is stored lowercase and compared without case by every operator. In `^`, `$`, `in`, `match` and their negations `_` matches any single character and `%` is a plain character. | Variable | Operators | Value | |---|---|---| | `$contact.email`, `phone`, `firstName`, `lastName` | text operators, `=`, `!=`, `ina`, `!ina`, `*`, `undefined` | string | | `$contact.country` | `=`, `!=`, `ina`, `!ina`, `*`, `undefined` | ISO 3166-1 alpha-2, upper case | | `$contact.date` | `=`, `!=`, `<`, `>`, `between`, `!between`, `*`, `undefined` | date the contact was added | | `$contact.isSubscribed` | `=` | marketing status: `S` subscribed, `U` unsubscribed, `B` bounced | | `$contact.emailQuality` | `=`, `!=`, `ina`, `!ina`, `*`, `undefined` | `Corp+`, `Corp` corporate, `Pers+`, `Pers` personal (`+` is the higher grade), `Edu` education, `Gov` government, `Risk` risky, `Temp` disposable, `Unk` unknown | | `$contact.tags` | `=`, `!=`, `ina`, `!ina`, `*`, `undefined` | tag ids from `list_tags` | | `$contact.segments` | `=`, `!=`, `ina`, `!ina` | ids from `list_segments`, as integers | | `$contact.emailSend`, `emailOpen`, `emailClick` | `=`, `!=`, `ina`, `!ina`, `*`, `undefined` | e-mail id, as `email_id` of a broadcast | | `$contact.emailSendCount`, `emailOpenCount`, `emailClickCount` | `=`, `!=`, `<`, `>`, `between`, `!between`, `*`, `undefined` | integer, not negative | | `$contact.emailSendDate`, `emailOpenDate`, `emailClickDate` | as `$contact.date` | the latest event | | `$contact.$shopifySpent`, `$shopifyOrders` | as the counts | integer | | `$contact.$shopifyOrderDate` | as `$contact.date` | the latest order | | `$contact.<field id>` | by the field type from `list_contact_fields`: text, integer, number, date or datetime | as the field; boolean and other fields are refused | `ina` and `!ina` on tags and segments take at least one id. On `$contact.tags`, `=` means the contact has that tag among its tags. `$contact.isSubscribed` compares the stored status code as the admin does: `S` does not match a contact who confirmed double opt-in, `U` does not match one who never subscribed or awaits double opt-in, and `B` matches every bounced contact. The contact statuses `subscribed`, `unsubscribed` and `bounced` are the broader groups. Ids are integers or strings of digits. A number is a 32-bit integer or a string holding one. A date is `YYYY-MM-DD` or ISO 8601 with an offset. For `$contact.date`, `$shopifyOrderDate` and datetime fields, a value at midnight is a whole day: `=` and `!=` cover the day, and the second value of `between` runs to its end. Date fields and `$contact.email*Date` compare with midnight exactly. Nested segments may not form a cycle. A list must reference each nested segment once, and not one nested inside another. Conditions are checked the way they run: nested segments must exist and the whole tree must compile, so an unknown variable or a value of the wrong type is refused. Conditions saved in the admin are returned as they are and may use other variables and values. null only together with non-empty `warnings`
    - `recipient_settings` RecipientSettings, required
      - `limit` integer, nullable: At most this many recipients; null when not limited
      - `sort` 'newest' | 'oldest' | 'random' | 'hottest', required: Which contacts a `limit` keeps: newest: added last. oldest: added first. random: a random choice. hottest: who opened or clicked most recently.
      - `quality_gate` EmailQualityGrade[], required: E-mail qualities left out of the audience; empty when none is
  - `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` ABTestCard, 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.
    - `test_percentage` integer, nullable: Percent of the audience the variants are tested on; null without A/B
    - `test_duration_hours` integer, nullable: Hours the test runs before the winner is chosen; null without A/B
  - `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
  - `tracking` Tracking, required
    - `add_utm_parameters` boolean, nullable: Whether UTM parameters are added to the e-mail's links; null without an e-mail

## Other responses

- `400`: Unsupported GSC-Version
- `401`: Missing or invalid API key or access token
- `403`: Access denied
- `404`: `site_not_found`: no such site in your account; `broadcast_not_found`: the site has no broadcast with this id, or it was deleted
- `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)