GET/v1/broadcastsbeta

List broadcasts

Needs: Read your data (mcp:read)
Plan: Any plan with API access
Limits: 300 a minute per key
Undo: Nothing to undo: this only reads.

Lists your WhatsApp broadcasts, newest first, with their status, channel, template, audience size and delivery numbers. Broadcasts are created and sent by your team in the app; the API reads them.

curl -X GET 'https://mcp.wa-api.cloud/v1/broadcasts?statuses=COMPLETE' \
  -H "Authorization: Bearer $API_KEY"

The code reads your key from $API_KEY.

Parameters

Parameters
Field	Type	What it is
search	string · query	Name contains this text.0–100 characters
statuses	array of string · query	Only these statuses (repeat the parameter).0–12 items
campaign_id	string · query	Only broadcasts of this campaign.0–20 characters
cursor	string · query	The `next_cursor` from the previous page. Cursors expire after 24 hours.1–2048 characters
limit	integer · query	How many items per page (1–100).1–100 · default `25`

Headers

Headers
Field	Type	What it is
Authorizationrequired	header	`Bearer $API_KEY` — your API key.
Api-Version	header	The API version to use, e.g. `2026-10-01`. Default: the version your key is pinned to.one of: `2026-10-01` · pattern `^\d{4}-\d{2}-\d{2}$`

Response `200`

A page of broadcasts.

Response fields
Field	Type	What it is
datarequired	array of object
idrequired	string
namerequired	string or null
statusrequired	string or null
channelrequired	object or null
idrequired	string or null
namerequired	string or null
templaterequired	object or null
namerequired	string or null
languagerequired	string or null
categoryrequired	string or null
audience_sizerequired	number or null	Estimated recipients when set up; stats.total once sending started.
scheduled_atrequired	string or null
created_atrequired	string or null
sandboxrequired	boolean
statsrequired	object or null
totalrequired	number
pendingrequired	number
sentrequired	number
deliveredrequired	number
readrequired	number
failedrequired	number
dndrequired	number	Skipped because the contact opted out / is on do-not-disturb.
respondedrequired	number
convertedrequired	number
delivery_raterequired	number or null	delivered / sent, 0-1.
read_raterequired	number or null	read / delivered, 0-1.
totalrequired	number
next_cursorrequired	string or null	Pass as "cursor" to get the next page; null when there are no more results.

Errors

Errors are application/problem+json. Branch on code.

Status	Code	When
400	invalid_input	A field is missing or has the wrong format. `errors[]` points at each field.
401	unauthenticated	The Authorization header is missing, the key is unknown, expired or revoked.
403	entitlement_required	The workspace's plan does not include API access (`api_access`).
403	insufficient_scope	The key does not have the permission this operation needs.
429	rate_limited	The key or workspace went over its rate limit. Wait for `Retry-After` seconds.
503	upstream_unavailable	A service behind the API is briefly unavailable. Safe to retry with backoff.

Examples

Completed broadcasts

Response 200

{
  "data": [
    {
      "id": "301",
      "name": "September sale",
      "status": "COMPLETE",
      "channel": {
        "id": "7",
        "name": "Main WhatsApp"
      },
      "template": {
        "name": "summer_sale",
        "language": "en",
        "category": "MARKETING"
      },
      "audience_size": 1000,
      "scheduled_at": null,
      "created_at": "2026-09-10T08:00:00Z",
      "sandbox": false,
      "stats": {
        "total": 1000,
        "pending": 0,
        "sent": 980,
        "delivered": 950,
        "read": 600,
        "failed": 20,
        "dnd": 5,
        "responded": 40,
        "converted": 10,
        "delivery_rate": 0.969,
        "read_rate": 0.632
      }
    }
  ],
  "next_cursor": null,
  "total": 1
}

Operation path

The same operation is also at POST /v1/ops/messaging_list_broadcasts, with every field in the JSON body.

Try it