list_broadcasts
List the broadcasts a project sent, newest first, with who sent them, the audience, how far each send got and how many members it could not reach.
Page a project's broadcast history. Every send since the release that introduced the ledger is a row: the door it came through (dashboard, bot, api, mcp, copilot) and who sent it, the segment with its plan, window or horizon, the tallies, and progress.line, the one sentence the creator reads on the dashboard's Broadcasts page ("Sent to 126 of 128, 2 could not be reached, in 48s"). The row is the REST resource, so an agent and an integration read the same figures.
filter keeps to one face: sending for the ones still moving (queued, sending or paused by the platform), completed, failed. status keeps to one exact status. Omit both for every broadcast.
History starts with the release that introduced it. A send made before it has
no row, so a broadcast_id remembered from an older broadcast.queued event
is RESOURCE_NOT_FOUND on get_broadcast.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Annotations
It reads and never changes anything.
Arguments
project_id*stringUUID of the project whose broadcasts to list.
filterstringoptionalOptional face: `sending` (queued, sending or paused), `completed` or `failed`. Omit for every broadcast.
statusstringoptionalOptional exact status: `queued`, `sending`, `paused`, `completed` or `failed`.
limitintegeroptionalMaximum rows per page (1..100).
1max100pageintegeroptional1-indexed page number.
1What it returns
{ "data": [ { "id": "0192f4a6-3c1e-7d2b-9a8f-4e5d6c7b8a90", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "status": "completed", "source": "copilot", "connector": null, "sent_by": { "id": "0191a0c4-2b7e-7a1d-8c3f-5d6e7f8a9b0c", "name": "Ada Lovelace" }, "audience": "customer", "pass_window_id": null, "plan_id": null, "expiring_within_days": null, "content": "<b>Doors open tonight</b> at 8.", "recipients_estimated": 128, "sent_count": 126, "failed_count": 2, "announcements_count": 0, "failures_by_kind": { "unreachable": 2 }, "progress": { "status": "completed", "done": 128, "total": 128, "failed": 2, "line": "Sent to 126 of 128, 2 could not be reached, in 48s" }, "parent_id": null, "last_error": null, "started_at": "2026-11-04T14:02:11+00:00", "finished_at": "2026-11-04T14:02:59+00:00", "duration_ms": 48000, "created_at": "2026-11-04T14:02:09+00:00", "updated_at": "2026-11-04T14:02:59+00:00" } ], "meta": { "page": 1, "limit": 25, "total": 1, "has_more": false }}progress.status is one of the five words every tracked piece of work uses (queued, running, paused, completed, failed); status is the broadcast's own (sending where progress says running). failures_by_kind splits the failed count by the connector's reading of why: unreachable (blocked the bot or left), not_permitted, target_missing (no account to reach), rate_limited, configuration, transient, other. parent_id names the broadcast a retry tried the missed members of.
How it fails
RESOURCE_NOT_FOUNDunknown project_id, another team's project, or one outside the token's scope:project: allow-list.
VALIDATION_FAILEDa filter or status the enum does not know.
TOKEN_MISSING_ABILITYtoken lacks broadcast:read.
How is this guide?
Last updated on