preview_broadcast_audience

Purpose

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.

Required ability

broadcast:send

There is no separate read ability — knowing who a broadcast would reach is the same privilege as reaching them.

Input schema

{
  "type": "object",
  "required": ["project_id"],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "UUID of the project to size a broadcast for."
    },
    "audience": {
      "type": "string",
      "description": "Size one segment only. Omit to receive every segment with its count."
    },
    "pass_window_id": {
      "type": "string",
      "description": "Needed to size the single-window pass segments; without it they report a null count."
    },
    "plan_id": {
      "type": "string",
      "description": "Optional plan UUID. Sizes each segment as narrowed to that plan."
    },
    "expiring_within_days": {
      "type": "integer",
      "description": "How far ahead `expiring_soon` looks, 1-90, default 7."
    }
  }
}

Output shape

Omitting audience returns every segment:

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

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.

Related

• broadcast_message — the send itself.
• Broadcasts API — the same preview over REST.