/v1/reports/staffbetaStaff 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.
Per staff member for a period: conversations handled, replies, closes, response and close times, and SLA breaches. Paged with cursor.
A metric this workspace cannot answer is null and listed in unavailable[] with the reason. Never read `null` as zero.
Try it
Query (6)
A named period. Default `last_7_days`. Weeks start on Monday.
First day, YYYY-MM-DD. Give `from` and `to` together; they override `preset`. Up to 186 days.
Last day (inclusive), YYYY-MM-DD.
IANA time zone, e.g. `Asia/Dubai`. Default: your workspace time zone.
How many items per page (1–100).
The `next_cursor` from the previous page. Cursors expire after 24 hours.
This only reads. It uses your real data and changes nothing.
Code and response
curl -X GET 'https://mcp.wa-api.cloud/v1/reports/staff' \ -H "Authorization: Bearer $API_KEY"
The code reads your key from $API_KEY.
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 |
| limit | integer · query | How many items per page (1–100).1–100 · default 25 |
| cursor | string · query | The next_cursor from the previous page. Cursors expire after 24 hours.1–2048 characters |
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 staff rows.
| 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. |
| sourcerequired | string | Where the per-staff numbers come from.one of: generated_report, live_closes |
| reportrequired | object or null | The generated report used, if any. coversMoreThanAsked = its period is wider than the range you asked for, so the numbers cover more days. |
| idrequired | string | |
| namerequired | string or null | |
| fromrequired | string | |
| torequired | string | |
| generated_atrequired | string or null | |
| timezonerequired | string or null | |
| covers_more_than_askedrequired | boolean | |
| datarequired | array of object | |
| staff_idrequired | string or null | null = unassigned / system. |
| namerequired | string or null | |
| conversationsrequired | integer or null | Conversation episodes attributed to this staff member in the range.-9007199254740991–9007199254740991 |
| handledrequired | integer or null | Episodes they actually held (assignment ledger), not just were assigned at the end.-9007199254740991–9007199254740991 |
| closedrequired | integer or null | -9007199254740991–9007199254740991 |
| repliedrequired | integer or null | -9007199254740991–9007199254740991 |
| untouchedrequired | integer or null | Episodes that never got a reply from them.-9007199254740991–9007199254740991 |
| messages_sentrequired | integer or null | -9007199254740991–9007199254740991 |
| avg_first_response_secondsrequired | number or null | Assignment → their first human reply (a bot reply does not stop the clock). |
| avg_time_to_close_secondsrequired | number or null | |
| reopenedrequired | integer or null | -9007199254740991–9007199254740991 |
| sla_breachesrequired | object or null | Null when the source cannot say (live fallback, or SLA not configured). |
| first_responserequired | integer or null | -9007199254740991–9007199254740991 |
| next_responserequired | integer or null | -9007199254740991–9007199254740991 |
| resolutionrequired | integer or null | -9007199254740991–9007199254740991 |
| totalrequired | integer or null | -9007199254740991–9007199254740991 |
| sla_compliance_raterequired | number or null | Met / (met + breached) over resolved clocks, 0-1. Not comparable with the per-policy compliance rate. |
| reason_coveragerequired | number or null | Live source only: fraction of their closes that recorded a reason. |
| populationrequired | object | How many staff the source ranked, and whether it cut the list. |
| totalrequired | integer or null | -9007199254740991–9007199254740991 |
| cappedrequired | boolean | |
| noterequired | string or null | |
| workload_nowrequired | array of object | Live snapshot, most waiting first. Empty when unavailable. |
| staff_idrequired | string or null | |
| namerequired | string or null | |
| waitingrequired | integer or null | -9007199254740991–9007199254740991 |
| oldest_wait_secondsrequired | number or null | |
| assigned_openrequired | integer or null | -9007199254740991–9007199254740991 |
| window_expiredrequired | integer or null | -9007199254740991–9007199254740991 |
| notesrequired | array of string | |
| next_cursorrequired | string or null | |
| 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. |
| 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 ( |
| 403 | forbidden | The key owner has no report permission. |
| 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 |
| 503 | upstream_unavailable | A service behind the API is briefly unavailable. Safe to retry with backoff. |
Examples
Last 7 days
Response 200
{
"data": [
{
"staff_id": "1203",
"name": "Priya Nair",
"conversations": 120,
"closed": 98,
"replied": 410,
"avg_first_response_seconds": 95,
"avg_time_to_close_seconds": 5200,
"sla_breaches": null,
"handled": null,
"untouched": null,
"messages_sent": null,
"reopened": null,
"sla_compliance_rate": null,
"reason_coverage": null
}
],
"next_cursor": null,
"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"
},
"unavailable": [],
"source": "generated_report",
"report": null,
"population": {
"total": null,
"capped": false,
"note": null
},
"workload_now": [],
"notes": []
}Operation path
The same operation is also at POST /v1/ops/reports_staff, with every field in the JSON body.