GET/v1/conversations/countsbeta

Count conversations

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.

Returns the inbox tab counts your key's staff member sees — all, unassigned, open, active (the customer wrote in the last 24 hours), pending reply, awaiting response, starred, closed and SLA breached — plus how many conversations have unread messages.

Counts stop at 100: a key listed in capped means "100 or more". counts is null when per-tab counts are not enabled for the workspace (then note says so and only unread is set).

Try it

Query (2)

unread_stateoptionalstring

Count unread messages only in open or only in closed conversations.

unread_mineoptionalboolean

Count unread messages only in conversations assigned to the key's staff member.

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

curl -X GET 'https://mcp.wa-api.cloud/v1/conversations/counts' \
  -H "Authorization: Bearer $API_KEY"

The code reads your key from $API_KEY.

Parameters

Parameters
Field	Type	What it is
unread_state	string · query	Count unread messages only in open or only in closed conversations.one of: `open`, `closed`
unread_mine	boolean · query	Count unread messages only in conversations assigned to the key's staff member.

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

Response fields
Field	Type	What it is
countsrequired	object or null	Per-tab counts; null when counts are not enabled for this workspace.
cappedrequired	array of string	Keys whose value hit the 100 cap (meaning "100 or more").
unreadrequired	number or null	Conversations with unread messages (capped at 100).
note	string

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

Inbox tab counts for a dashboard

Response 200

{
  "counts": {
    "all": 100,
    "unassigned": 4,
    "open": 12,
    "active": 7,
    "pending_reply": 3,
    "awaiting_response": 2,
    "starred": 0,
    "closed": 100,
    "breached": 1
  },
  "capped": [
    "all",
    "closed"
  ],
  "unread": 9
}

Operation path

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