# Get a broadcast

> One broadcast with its counts and, while it is sending, when the rest should go.

`GET /v1/broadcasts/{id}`

One broadcast with its counts and, while it is sending, when the rest should go.

Needs a key with the `messages:read` scope. [Keys and scopes](https://usebluebot.com/docs/concepts/api-keys)

## Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The broadcast’s id. Starts with `bc_` |

## Example

```bash
curl "https://usebluebot.com/api/v1/broadcasts/bc_1Hq2LxW9cVbN3mKpRtYs0a" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY"
```

```ts
import BlueBot from '@usebluebot/sdk';

const client = new BlueBot({ apiKey: process.env.BLUEBOT_API_KEY });

const broadcast = await client.broadcasts.get('bc_1Hq2LxW9cVbN3mKpRtYs0a');
console.log(broadcast);
```

```python
import os
from bluebot import BlueBot

client = BlueBot(api_key=os.environ["BLUEBOT_API_KEY"])

broadcast = client.broadcasts.get("bc_1Hq2LxW9cVbN3mKpRtYs0a")
print(broadcast)
```

## Response

`200`: The broadcast.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | A bc_ id. Starts with `bc_` |
| `object` | "broadcast" | Yes |   |
| `name` | string | Yes |   |
| `text` | string or null | Yes | The words, with `{{variables}}`, as you wrote them. Each person’s filled-in text is on their message. Null once they’re deleted, 30 days after the broadcast finished. |
| `text_deleted` | boolean | Yes | True once the words, and the values each person’s list row brought, were deleted 30 days after the broadcast finished. |
| `template_id` | string or null | Yes | The template the words came from, when one did. |
| `audience` | any | Yes | Who the broadcast goes to. |
| `service` | string | Yes | One of `auto`, `imessage`, `sms` |
| `state` | string | Yes | `draft`, `scheduled` (waiting for `send_at`), `sending`, `completed` or `canceled`. One of `draft`, `scheduled`, `sending`, `completed`, `canceled` |
| `send_at` | timestamp or null | Yes | When it starts, for a scheduled broadcast. |
| `started_at` | timestamp or null | Yes | When the first text was queued. |
| `completed_at` | timestamp or null | Yes | When every text had settled. |
| `canceled_at` | timestamp or null | Yes | When the rest was canceled. |
| `recipient_count` | integer | Yes | How many people it goes to, up to 500. |
| `counts` | map of integer | Yes | How many recipients are in each state: `pending`, `queued`, `sent`, `delivered`, `read`, `failed`, `skipped` and so on. |
| `estimate` | BroadcastEstimate or null | Yes | For a scheduled or sending broadcast, when the rest should go. Worked out on `GET /v1/broadcasts/{id}` and when it is made; null in lists. |
| `estimate.first_at` | timestamp or null | Yes | When the first text should go. |
| `estimate.last_at` | timestamp or null | Yes | When the last text should go, given your pace, quiet hours and daily limits. |
| `estimate.days` | integer | Yes | How many days the sending spans in your time zone. |
| `estimate.waits_for` | array of strings | Yes | Holds the texts will meet on the way: `quiet_hours`, `daily_new_people_limit`, `platform_daily_limit`. |
| `estimate.blocked_by` | string or null | Yes | A hold with no end that stops the broadcast from going, such as `plan_lapsed`. |
| `estimate.mac_online` | boolean | Yes | Whether your Mac is online now. The estimate assumes it stays on. |
| `created_via` | string | Yes | One of `dashboard`, `api`, `assistant`, `mcp`, `zapier`, `cli` |
| `created_at` | timestamp | Yes | When it was made. |

The answer, `200`:

```json
{
  "id": "bc_1Hq2LxW9cVbN3mKpRtYs0a",
  "object": "broadcast",
  "name": "Open house Saturday",
  "text": "Hi {{first_name|there}}, open house at 412 Oak St this Saturday 1–4. Reply STOP to opt out.",
  "text_deleted": false,
  "template_id": null,
  "audience": {
    "kind": "tags",
    "tags": [
      "buyer"
    ]
  },
  "service": "auto",
  "state": "scheduled",
  "send_at": "2026-11-14T15:00:00.000Z",
  "started_at": null,
  "completed_at": null,
  "canceled_at": null,
  "recipient_count": 42,
  "counts": {
    "pending": 41,
    "skipped": 1
  },
  "estimate": {
    "first_at": "2026-11-14T15:00:00.000Z",
    "last_at": "2026-11-14T15:14:20.000Z",
    "days": 1,
    "waits_for": [],
    "blocked_by": null,
    "mac_online": true
  },
  "created_via": "api",
  "created_at": "2026-11-13T19:41:00.000Z"
}
```

## Errors

Every refusal has the same envelope and a page of its own. These are the ones this operation can give.

| Code                                                    | Status | What it means                                                                                                                               |
| ------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| [`unauthorized`](https://usebluebot.com/docs/errors/unauthorized)             | 401    | The request carried no key, or a key BlueBot doesn’t know: mistyped, revoked, or a test key sent to the live API.                           |
| [`insufficient_scope`](https://usebluebot.com/docs/errors/insufficient_scope) | 403    | The key doesn’t carry the scope the endpoint needs. Each endpoint’s reference names its scope.                                              |
| [`rate_limited`](https://usebluebot.com/docs/errors/rate_limited)             | 429    | Too many requests. A key may make 120 requests a minute. The `RateLimit` header says how many are left, and `Retry-After` how long to wait. |
| [`internal`](https://usebluebot.com/docs/errors/internal)                     | 500    | Something went wrong on BlueBot’s side. It was reported. Send the request again; with an Idempotency-Key that is always safe.               |
| [`not_found`](https://usebluebot.com/docs/errors/not_found)                   | 404    | There is no such thing on this account. Ids are prefixed by kind, so a message id starts with `msg_`.                                       |

## Try it