preview_broadcast_audience
Size a broadcast without sending it. Returns every audience segment with its current recipient count.
Read-only. Returns how many members a broadcast would reach, either for one named segment or for every segment at once. Nothing is sent.
Call this before broadcast_message, every time, and show the human the count. An audience that silently resolves to everyone is the one broadcast mistake that cannot be undone.
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 to size a broadcast for.
audiencestringoptionalSize one segment only. Omit to receive every segment with its count.
pass_window_idstringoptionalNeeded to size the single-window pass segments; without it they report a null count.
plan_idstringoptionalOptional plan UUID. Sizes each segment as narrowed to that plan. Segments that cannot use a plan filter (`lead`, the pass segments) report their unnarrowed count and a null plan_id.
expiring_within_daysintegeroptionalHow far ahead `expiring_soon` looks, 1-90, default 7. Ignored by every other segment.
What it returns
{ "data": { "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "has_connected_bot": true, "segments": [ { "value": "customer", "label": "Customers Only", "description": "Members with an active paid subscription.", "requires_pass_window": false, "supports_plan_filter": true, "requires_expiring_within_days": false, "plan_id": null, "expiring_within_days": null, "recipient_estimate": 128, "estimated_seconds": 5 } ] }}Omitting audience returns every segment:
A segment that addresses a single window reports recipient_estimate: null unless a pass_window_id is supplied — it cannot be sized without knowing which window, and a misleading 0 would read as "nobody holds this".
supports_plan_filter and requires_expiring_within_days say which extra inputs each segment accepts, so an agent can decide what to ask a human for before proposing anything.
Unlike broadcast_message, a plan_id a segment cannot use is dropped for that segment rather than refused — the no-audience form sizes every segment in one call, and refusing would make a plan filter unusable for the very listing used to choose a segment. Each row reports the plan_id it actually applied, so nothing is silently ignored.
Check has_connected_bot before proposing a send: a project without one cannot broadcast at all.
How is this guide?
Last updated on