---
title: "Get broadcast by ID"
method: GET
path: "/v1/projects/{project_id}/broadcasts/{id}"
tags: ["Message"]
---

# Get broadcast by ID

`GET /v1/projects/{project_id}/broadcasts/{id}`

## Request

- Base URL: `https://api.telerivet.com`
- URL: `https://api.telerivet.com/v1/projects/{project_id}/broadcasts/{id}`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://telerivet.com/oauth/authorize`, token URL `https://api.telerivet.com/oauth/token`)

Retrieves the broadcast with the given ID.

## Path parameters

- `project_id` string, required
- `id` string, required

## Response `200`

Successful response

- Broadcast: Represents a collection of related outgoing messages. Typically, messages in a broadcast have the same content template and were sent at the same time; however, a broadcast can also contain messages with unrelated content and messages that were sent at different times. A broadcast is automatically created when sending a message to a group of contacts.
  - `id` string: ID of the broadcast
  - `recipients` object[]: List of recipients. Each recipient is an object with a string `type` property, which may be `"phone_number"`, `"group"`, or `"filter"`. If the type is `"phone_number"`, the `phone_number` property will be set to the recipient's phone number. If the type is `"group"`, the `group_id` property will be set to the ID of the group, and the `group_name` property will be set to the name of the group. If the type is `"filter"`, the `filter_type` property (string) and `filter_params` property (object) describe the filter used to send the broadcast. (API clients should not rely on a particular value or format of the `filter_type` or `filter_params` properties, as they may change without notice.)
  - `title` string: Title of the broadcast. If a title was not provided when the broadcast was sent, it is automatically set to a human readable description of the first few recipients (possibly truncated)
  - `time_created` integer: Time the broadcast was sent in Telerivet
  - `last_message_time` integer, nullable: Time the most recent message was queued to send in this broadcast
  - `last_send_time` integer, nullable: Time the most recent message was sent (or failed to send) in this broadcast, or null if no messages have been sent yet
  - `status_counts` object: An object whose keys are the possible status codes (`"queued"`, `"sent"`, `"failed"`, `"failed_queued"`, `"delivered"`, `"not_delivered"`, and `"cancelled"`), and whose values are the number of messages in the broadcast currently in that status.
  - `message_count` integer: The total number of messages created for this broadcast. For large broadcasts, the messages may not be created immediately after the broadcast is sent. The `message_count` includes messages in any status, including messages that are still queued.
  - `estimated_count` integer: The estimated number of messages in this broadcast when it is complete. The `estimated_count` is calculated at the time the broadcast is sent. When the broadcast is completed, the `estimated_count` may differ from `message_count` if there are any blocked contacts among the recipients (blocked contacts are included in `estimated_count` but not in `message_count`), if any contacts don't have phone numbers, or if the group membership changed while the broadcast was being sent.
  - `num_parts` number, nullable: The total number of SMS parts that have been sent in this broadcast. The number of SMS parts does not include messages that are still queued, or messages that failed to send.
  - `message_type` 'sms' | 'mms' | 'ussd' | 'ussd_session' | 'call' | 'chat' | 'service': Type of message sent from this broadcast
  - `content` string: The text content of the message (null for USSD messages and calls)
  - `audio_url` string: For voice calls, the URL of an MP3 file to play when the contact answers the call
  - `tts_lang` 'en-US' | 'en-GB' | 'en-GB-WLS' | 'en-AU' | 'en-IN' | 'da-DK' | 'nl-NL' | 'fr-FR' | 'fr-CA' | 'de-DE' | 'is-IS' | 'it-IT' | 'pl-PL' | 'pt-BR' | 'pt-PT' | 'ru-RU' | 'es-ES' | 'es-US' | 'sv-SE': For voice calls, the language of the text-to-speech voice
  - `tts_voice` 'female' | 'male': For voice calls, the text-to-speech voice
  - `replace_variables` boolean: Set to true if Telerivet will render variables like [[contact.name]] in the message content, false otherwise
  - `status` 'queuing' | 'sending' | 'complete' | 'cancelled' | 'pending_review': The current status of the broadcast. `pending_review` is returned by sendBroadcast when Message Review is enabled and the broadcast was submitted for review instead of being sent; in that case the response contains a `scheduled_message_id` property instead of the other broadcast properties.
  - `source` 'phone' | 'provider' | 'web' | 'api' | 'service' | 'webhook' | 'scheduled' | 'integration' | 'mcp' | 'welcome': How the message originated within Telerivet
  - `simulated` boolean: Whether this message was simulated within Telerivet for testing (and not actually sent to or received by a real phone)
  - `track_clicks` boolean: If true, URLs in the message content will automatically be replaced with unique short URLs.
  - `clicked_count` integer, nullable: The number of messages in this broadcast containing short links that were clicked. At most one click per message is counted. If track_clicks is false, this property will be null.
  - `label_ids` string: List of IDs of labels applied to all messages in the broadcast
  - `media` object[]: Array of media attachments for the text message. This property is undefined for messages that do not contain media files.
    - `url` string: URL of the media file. Note: For files stored by Telerivet (including uploaded files and incoming media attachments), the URL is temporary and may not be valid for more than 1 day.
    - `type` string: MIME type of the media file, or `route_vcard` for the Contact Card of the sending route in a message that has not been sent yet (in which case the other properties are null)
    - `filename` string: Original filename
    - `size` integer: File size in bytes
    - `file_id` string: ID of the stored file, if applicable
  - `vars` object: Custom variables stored for this broadcast. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.
  - `route_params` object, nullable: Route-specific parameters for the messages in the broadcast. When sending messages via chat apps such as WhatsApp, the route_params parameter can be used to send messages with app-specific features such as quick replies and link buttons. For more details, see Route-Specific Parameters.
  - `variants` object[], nullable: Alternative message bodies used instead of the default message body when their conditions match. Allows sending different message bodies depending on the route that sends the message, or the contact that the message is sent to. Each variant has conditions and its own message body. When each message is sent, the first variant whose conditions match is used instead of the default message body; if no variant matches, the default message body is used. A variant replaces the entire message body: content, media, route_params, track_clicks and short_link_params that are not specified in the variant are empty, not inherited from the default message body. Conditions are evaluated when the message is sent by a particular basic route, and can use the same variables as outgoing message content: contact variables such as [[contact.name]] and [[contact.vars.\*]], [[to_number]], [[time]], [[project.\*]], and variables of the basic route sending the message: [[phone.type]] (e.g. whatsapp), [[phone.id]], [[phone.vars.\*]], and [[phone.supports_quick_replies]], [[phone.supports_link_button]], [[phone.supports_native_attachments]] (1 if the route supports the feature, otherwise 0). Variables may include filters, e.g. [[contact.vars.language|default:"en"]]. For all available variables, see the [Variable Reference](https://telerivet.com/api/rest#variables). For A/B testing, a variant can have a random split (split_percent) so that it is only used for a random percentage of recipients, e.g. a single variant with split_percent 50 is used for about half of the recipients, and the default message body for the others. A random split can be combined with other conditions to run separate A/B tests for different routes or contacts. Since the first matching variant is used, list more specific variants before more general ones. For example, a variant with a condition `[[contact.vars.language]] is 'fr'` and split_percent 50 must be listed before a variant with only the condition `[[contact.vars.language]] is 'fr'`. Up to 10 variants are supported, each with up to 5 conditions.
    - `conditions` object[]: Conditions for using this variant (up to 5). Required unless the variant has a `split_percent`.
      - `variable` string: Variable to compare (required except when condition type is `contact_is_in_group` or `contact_not_in_group`), surrounded by double square brackets, e.g. `[[phone.type]]` or `[[contact.vars.lang]]`
      - `type` string, required: Type of condition
      - `value` string, required: Value to compare with the variable, or the group name if the condition type is `contact_is_in_group` or `contact_not_in_group`
    - `op` string: Operator to join multiple conditions: `and` (default) or `or`. If `split_percent` is specified, `or` is not supported.
    - `split_percent` integer: For A/B testing, the approximate percentage of recipients (1-100) randomly selected for this variant. Each variant with a `split_percent` is used for a separate random group of recipients, and recipients not selected for any variant receive the default message body (e.g. a single variant with a `split_percent` of 50 is used for about half of the recipients). Recipients are assigned to groups deterministically, so each contact is in the same group for all messages in the same broadcast or campaign. The total `split_percent` of all variants with the same conditions can be at most 100. If `split_percent` is omitted, the variant is used for all recipients that match its conditions.
    - `content` string: Content of the message when this variant is used
    - `media` object[]: Array of media attachments when this variant is used (same format as the `media` parameter)
    - `route_params` object: Route-specific parameters when this variant is used
    - `track_clicks` boolean: Whether to shorten links and track link clicks when this variant is used
    - `short_link_params` object: Parameters for short links when `track_clicks` is enabled (same format as the `short_link_params` parameter)
  - `variant_stats` object[], nullable: Statistics for the messages sent with each message variant, to compare the performance of each variant (e.g. for A/B tests). The first item has statistics for messages sent with the default message body. This property is only returned when retrieving a single broadcast (not when querying broadcasts), and is undefined for broadcasts without message variants.
    - `variant` integer: Index of the variant in `variants` (starting from 0), or null for the default message body
    - `message_count` integer: The number of messages sent with this variant
    - `status_counts` object: Number of messages sent with this variant with each status, in the same format as `status_counts`
    - `num_parts` number: The total number of SMS parts sent with this variant
    - `reply_count` integer: The number of replies received in response to messages sent with this variant
    - `clicked_count` integer: The number of messages sent with this variant containing short links that were clicked (null if track_clicks is false)
    - `price` number: The total price of the messages sent with this variant, if known
    - `price_currency` string: The currency of the price, if applicable
  - `price` number, nullable: The total price of all messages in this broadcast, if known.
  - `price_currency` string: The currency of the message price, if applicable.
  - `reply_count` integer: The number of replies received in response to a message sent in this broadcast. (Replies are not included in `message_count` ,`status_counts`, or `price`.)
  - `last_reply_time` integer, nullable: Time the most recent reply was received in response to a message sent in this broadcast, or null if no replies have been sent yet
  - `route_id` string: ID of the phone or route used to send the broadcast (if applicable)
  - `service_id` string: The service associated with this broadcast (for voice calls, the service defines the call flow)
  - `url` string, nullable: URL to this broadcast in the Telerivet web app
  - `user_id` string: ID of the Telerivet user who sent the broadcast (if applicable)
  - `project_id` string: ID of the project this broadcast belongs to
  - `is_template` boolean: Set to true if Telerivet will render variables like [[contact.name]] in the message content
  - `recipients_str` string: A string with a human readable description of the first few recipients (possibly truncated)

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key or Bearer token
- `404`: Resource not found

---

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