GET/v1/reports/broadcastsbeta

Broadcasts report

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.

Broadcasts created in a period, newest first, each with audience, sent, delivered, read, failed and opted-out counts. Test sends are left out unless you ask.

A metric this workspace cannot answer is null and listed in unavailable[] with the reason. Never read `null` as zero.

Try it

Query (7)

presetoptionalstring

A named period. Default `last_7_days`. Weeks start on Monday.

fromoptionalstring

First day, YYYY-MM-DD. Give `from` and `to` together; they override `preset`. Up to 186 days.

tooptionalstring

Last day (inclusive), YYYY-MM-DD.

timezoneoptionalstring

IANA time zone, e.g. `Asia/Dubai`. Default: your workspace time zone.

include_sandboxoptionalboolean

Include test broadcasts.

cursoroptionalstring

The `next_cursor` from the previous page. Cursors expire after 24 hours.

limitoptionalinteger

How many items per page (1–100).

This only reads. It uses your real data and changes nothing.

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

The code reads your key from $API_KEY.

Parameters

Parameters
Field	Type	What it is
preset	string · query	A named period. Default `last_7_days`. Weeks start on Monday.one of: `today`, `yesterday`, `last_7_days`, `last_14_days`, `last_30_days`, `this_month`, `last_month`, `this_week`, `last_week`
from	string · query	First day, YYYY-MM-DD. Give `from` and `to` together; they override `preset`. Up to 186 days.pattern `^\d{4}-\d{2}-\d{2}$`
to	string · query	Last day (inclusive), YYYY-MM-DD.pattern `^\d{4}-\d{2}-\d{2}$`
timezone	string · query	IANA time zone, e.g. `Asia/Dubai`. Default: your workspace time zone.1–64 characters
include_sandbox	boolean · query	Include test broadcasts.default `false`
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
rangerequired	object	The range and timezone these numbers were counted in — always state it when reporting them.
fromrequired	string	First local day (YYYY-MM-DD), inclusive.
torequired	string	Last local day (YYYY-MM-DD), inclusive.
daysrequired	integer	Number of local days in the range.-9007199254740991–9007199254740991
timezonerequired	string	IANA timezone the days were counted in.
started_atrequired	string	Range start as a UTC instant (ISO-8601).
ended_atrequired	string	Range end as a UTC instant (ISO-8601), exclusive.
presetrequired	string or null	The named range used, if any.
totalsrequired	object
broadcastsrequired	integer	-9007199254740991–9007199254740991
audiencerequired	integer	-9007199254740991–9007199254740991
sentrequired	integer	-9007199254740991–9007199254740991
deliveredrequired	integer	-9007199254740991–9007199254740991
readrequired	integer	-9007199254740991–9007199254740991
failedrequired	integer	-9007199254740991–9007199254740991
opted_outrequired	integer	-9007199254740991–9007199254740991
delivery_raterequired	number or null
read_raterequired	number or null
datarequired	array of object	One page of broadcasts, newest first.
idrequired	string
namerequired	string or null
statusrequired	string or null
created_atrequired	string or null
sandboxrequired	boolean	true = a test send, not real traffic.
channelrequired	object or null
idrequired	string or null
namerequired	string or null
templaterequired	object or null
namerequired	string or null
languagerequired	string or null
statsrequired	object
audiencerequired	integer	Recipients in the audience (summary total, or the estimate before sending started).-9007199254740991–9007199254740991
sentrequired	integer	-9007199254740991–9007199254740991
deliveredrequired	integer	-9007199254740991–9007199254740991
readrequired	integer	Marked read — depends on the recipient having read receipts on.-9007199254740991–9007199254740991
failedrequired	integer	-9007199254740991–9007199254740991
pendingrequired	integer	-9007199254740991–9007199254740991
opted_outrequired	integer	Skipped because the contact is on do-not-disturb / opted out.-9007199254740991–9007199254740991
respondedrequired	integer	-9007199254740991–9007199254740991
delivery_raterequired	number or null
read_raterequired	number or null
scannedrequired	integer	Broadcasts inspected while walking the list to cover the range.-9007199254740991–9007199254740991
truncatedrequired	boolean	true = the walk stopped early (page budget or time); older broadcasts in the range may be missing and the totals are a lower bound.
notesrequired	array of string
next_cursorrequired	string or null	Pass as "cursor" for the next page; null when there are no more.
unavailablerequired	array of object	Metrics that are UNKNOWN (missing data source), not zero. Say so when reporting; do not fill them in with 0.
metricrequired	string	Which metric or section is missing, e.g. "messages.read".
reasonrequired	string	Why it is missing (not supported by this server version, service not configured, forbidden, temporarily unavailable…).

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. The range is reversed, in the future, longer than 186 days, or the time zone is unknown.
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

This month

Response 200

{
  "data": [
    {
      "id": "8812",
      "name": "September sale",
      "status": "COMPLETED",
      "created_at": "2026-09-15T07:00:00Z",
      "channel": {
        "id": "301",
        "name": "Main WhatsApp"
      },
      "template": {
        "name": "sept_sale",
        "language": "en_US"
      },
      "stats": {
        "audience": 5300,
        "sent": 5210,
        "delivered": 5096,
        "read": 3920,
        "failed": 44,
        "opted_out": 18,
        "pending": -9007199254740991,
        "responded": -9007199254740991,
        "delivery_rate": null,
        "read_rate": null
      },
      "sandbox": false
    }
  ],
  "next_cursor": null,
  "range": {
    "from": "2026-09-01",
    "to": "2026-09-23",
    "days": 23,
    "timezone": "Asia/Dubai",
    "started_at": "2026-09-16T20:00:00Z",
    "ended_at": "2026-09-23T20:00:00Z",
    "preset": "this_month"
  },
  "unavailable": [],
  "totals": {
    "broadcasts": -9007199254740991,
    "audience": -9007199254740991,
    "sent": -9007199254740991,
    "delivered": -9007199254740991,
    "read": -9007199254740991,
    "failed": -9007199254740991,
    "opted_out": -9007199254740991,
    "delivery_rate": null,
    "read_rate": null
  },
  "scanned": -9007199254740991,
  "truncated": false,
  "notes": []
}

Operation path

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