# Cancel a broadcast

`POST /v1/broadcasts/{id}/cancel`

Stops a broadcast for good. Messages already being sent finish. The rest are never sent and stay `pending`.

Needs `broadcasts:write`.

## Path parameters

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

## Headers

- `Idempotency-Key` (string): Makes this request safe to retry. See [Retrying safely](/reference/api/#retrying-safely). 1 to 255 characters.

## What you can cancel

A broadcast that is `preparing`, `scheduled`, `queued`, `processing` or `paused`. The request takes no body: send none, or `{}`.

## Example

```sh
curl -X POST https://app.soosh.io/v1/broadcasts/9e1b3d5f-7a2c-4e48-b0d6-2c4e6a8c0e13/cancel \
  -H "Authorization: Bearer $SOOSH_API_KEY" \
  -H "Idempotency-Key: cancel-broadcast-example-1"
```

Response 200:

```json
{
  "id": "9e1b3d5f-7a2c-4e48-b0d6-2c4e6a8c0e13",
  "name": "Diwali offer",
  "status": "cancelled",
  "template": {
    "id": "8d2f4c1e-7a3b-4e59-b0c6-1f2e3d4c5b6a",
    "name": "diwali_offer",
    "language": "en"
  },
  "number_id": "0f6d3c1e-5b7a-4c52-9a55-3f6a2d5c8b10",
  "send_at": null,
  "started_at": "2026-10-14T11:20:17.002Z",
  "completed_at": null,
  "paused_reason": null,
  "counts": {
    "total": 250,
    "sent": 140,
    "delivered": 118,
    "read": 42,
    "failed": 2,
    "replied": 5,
    "clicked": 3
  },
  "skipped": {
    "opted_out": 6,
    "duplicate": 2,
    "invalid_phone": 1
  },
  "created_by": {
    "type": "api_key",
    "id": "5e1d2c3b-4a59-4f68-8e7d-6c5b4a392817",
    "name": "Order system"
  },
  "created_at": "2026-10-14T11:20:15.640Z"
}
```

## Returns

200. The broadcast, now `cancelled`. It also sends a `broadcast.status` event.

## Errors

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

- 409 `invalid_state`: The broadcast has any other status, including one that completed a moment ago.
- 404 `not_found`: There is no broadcast with this ID in your workspace.
- 409 `idempotency_in_progress`: A request with the same `Idempotency-Key` is still running.
- 422 `idempotency_mismatch`: The `Idempotency-Key` was used before for a different request, or by another of your API keys.