# List a broadcast's recipients

`GET /v1/broadcasts/{id}/recipients`

Returns a page of a broadcast's recipients and what happened to each message, newest first. A broadcast still `preparing` lists the recipients collected so far.

Needs `broadcasts:read`.

## Path parameters

- `id` (string, uuid): The broadcast's ID.

## Query parameters

- `limit` (integer): How many items to return. From 1 to 100. Default `25`.
- `cursor` (string): The `next_cursor` of the previous page, unchanged. A cursor that was changed, or made for another broadcast or status filter, is `400 invalid_request`.
- `status` (string): Only recipients with this status. Any other value is `400 invalid_request`. One of `pending`, `sent`, `delivered`, `read`, `failed`.

## Phone numbers

A key with `broadcasts:read` sees recipients' full phone numbers. The app's masking settings don't apply to keys.

## Example

```sh
curl "https://app.soosh.io/v1/broadcasts/2e4a6c8e-0b1d-4f3a-a5c7-9e1b3d5f7a2c/recipients?status=failed" \
  -H "Authorization: Bearer $SOOSH_API_KEY"
```

Response 200:

```json
{
  "data": [
    {
      "phone": "+919812345678",
      "name": "Rahul",
      "status": "failed",
      "message_id": "9b1d3f5a-7c2e-4a40-b6d8-0e2f4a6c8b13",
      "error": {
        "code": 131026,
        "message": "Message undeliverable"
      },
      "sent_at": "2026-10-14T09:31:42.305Z",
      "delivered_at": null,
      "read_at": null,
      "replied_at": null
    }
  ],
  "next_cursor": null
}
```

## Returns

200. A page of recipients.

## Errors

Besides the ones every request can get (https://docs.soosh.io/reference/api/errors/):

- 404 `not_found`: There is no broadcast with this ID in your workspace.