GET /api/v1/broadcasts/:id

Query contract

• Required scope is broadcasts:read. Another account’s inaccessible ID returns 404 not_found.
• limit defaults to 20 and is clamped from 1 to 100; offset defaults to zero.
• status supports all, pending, processing, sent, delivered, read, replied, read_no_reply, failed, blocked, invalid, and cancelled. Unknown values become all.
• failure_code is bounded to 120 characters and q to 200. Optional flags include retarget facets and read-no-reply total.

Response shape

{
  "broadcast": { "id": "broadcast_uuid", "current_run": {}, "runs": [] },
  "recipients": [],
  "totalRecipientsMatchingFilter": 0,
  "readNoReplyTotal": 0,
  "retargetFacets": {},
  "hasMoreRecipients": false,
  "recipientOffset": 0,
  "recipientLimit": 20
}

Interpret status safely

• Queued, preparing, processing, sent, delivered, read, failed, blocked, and invalid describe different stages or classifications.
• Sent is provider submission, not delivery. Delivered and Read require later status evidence.
• Campaign aggregates can span multiple runs while recipient review and pagination remain scoped by current response data.
• Blocked and invalid recipients are preparation outcomes rather than provider delivery receipts.

Poll and recover

Poll conservatively and stop when the campaign reaches a stable terminal state. Filter failed, blocked, or invalid recipients and inspect diagnostics before retargeting. Use hasMoreRecipients with offset and limit rather than relying on the obsolete pagination object shape.