GET/v1/reports/conversationsbeta

Conversations 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.

Conversation outcomes for a period: closes, close reasons, reopen rate and median time to close, per day and per channel — plus how many customers are waiting right now.

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

Try it

Query (5)

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.

channel_idsoptionallist

Only these channels.

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

curl -X GET 'https://mcp.wa-api.cloud/v1/reports/conversations?preset=last_7_days' \
  -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
channel_ids	array of string · query	Only these channels.0–50 itemsSigned in? Pick one from your data with “My data”.

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`

The report.

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
closesrequired	integer or null	Times a conversation was closed in the range (a conversation can be closed more than once).-9007199254740991–9007199254740991
conversationsrequired	integer or null	Distinct conversations behind those closes.-9007199254740991–9007199254740991
with_reasonrequired	integer or null	-9007199254740991–9007199254740991
reason_coveragerequired	number or null	Fraction of closes that recorded a reason (0-1).
reopen_eligiblerequired	integer or null	Closes whose reopen window has finished, so the reopen rate can be measured.-9007199254740991–9007199254740991
reopenedrequired	integer or null	-9007199254740991–9007199254740991
reopen_raterequired	number or null	reopened / reopenEligible (0-1); null when nothing is eligible yet.
median_close_secondsrequired	number or null	Median time from opening to closing. Null for chunked ranges (medians cannot be merged).
median_reopen_gap_secondsrequired	number or null
previous_periodrequired	object or null	The same length immediately before the range, same filters; null when the platform could not compute it or the range was chunked.
closesrequired	integer or null	Times a conversation was closed in the range (a conversation can be closed more than once).-9007199254740991–9007199254740991
conversationsrequired	integer or null	Distinct conversations behind those closes.-9007199254740991–9007199254740991
with_reasonrequired	integer or null	-9007199254740991–9007199254740991
reason_coveragerequired	number or null	Fraction of closes that recorded a reason (0-1).
reopen_eligiblerequired	integer or null	Closes whose reopen window has finished, so the reopen rate can be measured.-9007199254740991–9007199254740991
reopenedrequired	integer or null	-9007199254740991–9007199254740991
reopen_raterequired	number or null	reopened / reopenEligible (0-1); null when nothing is eligible yet.
median_close_secondsrequired	number or null	Median time from opening to closing. Null for chunked ranges (medians cannot be merged).
median_reopen_gap_secondsrequired	number or null
by_dayrequired	array of object
daterequired	string
closesrequired	integer	-9007199254740991–9007199254740991
reopenedrequired	integer	-9007199254740991–9007199254740991
by_channelrequired	array of object
channel_idrequired	string
namerequired	string or null
typerequired	string or null
closesrequired	integer	-9007199254740991–9007199254740991
reopenedrequired	integer	-9007199254740991–9007199254740991
reopen_raterequired	number or null
top_close_reasonsrequired	array of object	Up to 10, most closes first. reasonId null = closed without a reason.
reason_idrequired	string or null
namerequired	string or null
closesrequired	integer	-9007199254740991–9007199254740991
sharerequired	number or null
waiting_nowrequired	object or null
as_ofrequired	string or null
totalrequired	integer or null	-9007199254740991–9007199254740991
unassignedrequired	integer or null	-9007199254740991–9007199254740991
median_wait_secondsrequired	number or null
agerequired	object	Waiting conversations by how long they have been waiting (under_1h, h1_to_4, h4_to_24, d1_to_7, over_7d, unknown).
windowrequired	object	Waiting conversations by 24-hour WhatsApp reply window (expired, closing_1h, closing_4h, closing_24h, open_over_24h, unknown).
stalerequired	boolean	true = served from the platform's short cache, not computed this second.
response_timesrequired	object or null	Null when no generated staff report covers this range — ask a manager to generate one in the panel (Analytics → Reports).
avg_first_response_secondsrequired	number or null	Assignment → first human reply. A bot reply does not stop this clock.
avg_time_to_close_secondsrequired	number or null
avg_time_to_assignment_secondsrequired	number or null	Opened → first assignment (queue time). Company-wide only, never per staff.
from_reportrequired	object
idrequired	string
namerequired	string or null
fromrequired	string
torequired	string
generated_atrequired	string or null
notesrequired	array of string
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

Last 7 days

Response 200

{
  "range": {
    "from": "2026-09-17",
    "to": "2026-09-23",
    "days": 7,
    "timezone": "Asia/Dubai",
    "started_at": "2026-09-16T20:00:00Z",
    "ended_at": "2026-09-23T20:00:00Z",
    "preset": "last_7_days"
  },
  "totals": {
    "closes": 406,
    "conversations": 398,
    "reopened": 31,
    "reopen_rate": 0.078,
    "median_close_seconds": 5400,
    "with_reason": null,
    "reason_coverage": null,
    "reopen_eligible": null,
    "median_reopen_gap_seconds": null
  },
  "by_day": [
    {
      "date": "2026-09-23",
      "closes": 61,
      "reopened": 4
    }
  ],
  "by_channel": [
    {
      "channel_id": "301",
      "name": "Main WhatsApp",
      "closes": 380,
      "reopened": 29,
      "type": null,
      "reopen_rate": null
    }
  ],
  "top_close_reasons": [
    {
      "reason_id": "2",
      "name": "Resolved",
      "closes": 290,
      "share": null
    }
  ],
  "waiting_now": {
    "total": 9,
    "unassigned": 4,
    "median_wait_seconds": 840,
    "as_of": null,
    "age": {},
    "window": {},
    "stale": false
  },
  "notes": [],
  "unavailable": [],
  "previous_period": null,
  "response_times": null
}

Operation path

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