# GET /v1/broadcasts

List the broadcasts

The broadcasts of this server, newest first, a page at a time.

Takes a server key (`sk_…`, or `sk_test_…` on a test server) as a bearer token. TypeScript: `sendora.broadcasts.list(query)`. Python: `sendora.broadcasts.list(limit=..., after=...)`.

## Parameters

- `limit` (query, integer (1 to 100)): Page size, 1 to 100.
- `after` (query, string (uuid)): The `next` value of the previous page.

## Responses

### 200 A page of the broadcasts, newest first.

- `broadcasts` (array of object, required)
  - `broadcastId` (string (uuid), required)
  - `streamId` (string (uuid), required): The broadcast stream the messages go on.
  - `status` ("accepted" | "processing" | "completed" | "cancelled", required): accepted until the first message leaves, processing while messages are leaving, completed when every message has left or failed, cancelled once cancelled.
  - `from` (string, required)
  - `subject` (string, required)
  - `tag` (string or null, required)
  - `metadata` (map of string to string, required)
  - `total` (integer, required): Messages stored, after suppressed addresses were dropped.
  - `released` (integer, required): Messages handed to the mail server so far.
  - `failed` (integer, required): Messages that could not be handed over, cancelled ones included.
  - `suppressed` (integer, required): Addresses dropped from the list for standing on the stream’s suppression list.
  - `submittedAt` (string (date-time), required)
  - `completedAt` (string (date-time) or null, required): Set once nothing is left to send, or on cancel.
- `next` (string (uuid) or null, required): Pass as `after` for the next page; null on the last.

Example:

```json
{
  "broadcasts": [
    {
      "broadcastId": "2f1c8a4e-3b6d-4f0a-9c21-7d5e6a8b9c01",
      "streamId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "status": "processing",
      "from": "news@acme.se",
      "subject": "News from Acme in October",
      "tag": "newsletter-2026-10",
      "metadata": {},
      "total": 2,
      "released": 1,
      "failed": 0,
      "suppressed": 0,
      "submittedAt": "2026-10-01T08:00:00.000Z",
      "completedAt": null
    }
  ],
  "next": null
}
```

## Errors

Every error answers `error`, the code, and `message`, a sentence for a person. A code that adds fields is shown in full below the table.

| Code | Status | Meaning |
| --- | --- | --- |
| `invalid_request` | 400 | The body, the query or a header does not match what the route takes. |
| `unauthorized` | 401 | The key is missing, malformed or revoked. |
| `wrong_token_kind` | 403 | The key is of the other kind: a server key (sk_) where an account key (ak_) is needed, or the reverse. The message names the kind the operation takes. |

### `invalid_request`

- `issues` (array of object): One entry per invalid field; absent when a header is wrong.
  - `path` (string, required): The field, dotted, such as to.0.email; empty when the whole body is wrong.
  - `message` (string, required)

Example:

```json
{
  "error": "invalid_request",
  "message": "The request is invalid: to.0: Invalid email address",
  "issues": [
    {
      "path": "to.0",
      "message": "Invalid email address"
    }
  ]
}
```