CXone v2 Reporting API: Querying agent state history for last 24 hours

NICE CXone API & Integrations
1

I’m trying to pull agent state history for the last 24 hours using the CXone Reporting API. I’ve got the endpoint /api/v2/analytics/users/summary, but the time range parameters seem tricky. When I pass startDateTime and endDateTime in ISO 8601 format, I get a 200 OK but the response is empty. Am I missing a filter or is there a different endpoint for state history specifically? Here’s my current request body:

{
 "interval": "PT1H",
 "groupBy": ["user_id"]
}

Not sure what’s going wrong.

2

You’re hitting the wrong endpoint. /api/v2/analytics/users/summary gives you aggregate metrics, not state history. The docs state: “Use /api/v2/analytics/agents/queues/ranges for detailed state breakdowns.”

Here is what you need to change:

  • Switch to /api/v2/analytics/agents/queues/ranges. It supports the $filter syntax for state types.
  • Use this filter: $filter=stateType eq 'agent' and state eq 'available'. Adjust available to whatever state you’re tracking.
  • Set the time range correctly. The body needs interval: "PT1H" and proper ISO 8601 dates.
  • Check your scopes. You need analytics:reports:view and analytics:agent:view.

Try this curl:

curl -X POST "https://api.mypurecloud.com/api/v2/analytics/agents/queues/ranges" \
 -H "Authorization: Bearer {token}" \
 -H "Content-Type: application/json" \
 -d '{
 "interval": "PT1H",
 "groupBy": ["agent"],
 "filter": "stateType eq 'agent' and state eq 'available'",
 "dateFrom": "2023-10-25T00:00:00Z",
 "dateTo": "2023-10-26T00:00:00Z"
 }'

The summary endpoint doesn’t store historical state logs.