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.

Request

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"

const res = await fetch('https://app.soosh.io/v1/broadcasts/9e1b3d5f-7a2c-4e48-b0d6-2c4e6a8c0e13/cancel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SOOSH_API_KEY}`,
    'Idempotency-Key': 'cancel-broadcast-example-1',
  },
});
console.log(await res.json());

import os
import requests

res = requests.post(
    "https://app.soosh.io/v1/broadcasts/9e1b3d5f-7a2c-4e48-b0d6-2c4e6a8c0e13/cancel",
    headers={"Authorization": f"Bearer {os.environ['SOOSH_API_KEY']}", "Idempotency-Key": "cancel-broadcast-example-1"},
)
print(res.json())

Response200

{
  "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"
}

Every field of the broadcast object

Path parameters

id string · uuid

The broadcast’s ID.

Headers

Idempotency-Key string

Makes this request safe to retry. See 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 {}.

Returns

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

Errors

Besides the ones every request can get:

409invalid_stateThe broadcast has any other status, including one that completed a moment ago.

404not_foundThere is no broadcast with this ID in your workspace.

409idempotency_in_progressA request with the same Idempotency-Key is still running.

422idempotency_mismatchThe Idempotency-Key was used before for a different request, or by another of your API keys.