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 using the wrong endpoint. /api/v2/analytics/users/summary provides aggregated metrics, not detailed state history. The documentation directs you to use the /api/v2/analytics/users/details endpoint for granular agent state breakdowns.

Here’s what you need to adjust:

  • Switch to /api/v2/analytics/users/details. This supports filtering by state.
  • Use a $filter to specify state types. For example: $filter=stateType eq 'AgentState' and state eq 'Available'. Adjust Available to the specific state you need.
  • Ensure correct time range parameters. Include interval: "PT1H" and valid ISO 8601 dates.
  • Verify your API permissions. You’ll need analytics:reports:view and analytics:agent:view scopes.

Here’s a sample curl request:

curl -X POST "https://api.cxone.net/api/v2/analytics/users/details" \
 -H "Authorization: Bearer {token}" \
 -H "Content-Type: application/json" \
 -d '{
 "interval": "PT1H",
 "groupBy": ["user_id"],
 "filter": "stateType eq 'AgentState' and state eq 'Available'",
 "dateFrom": "2023-10-25T00:00:00Z",
 "dateTo": "2023-10-26T00:00:00Z"
 }'

The summary endpoint doesn’t log historical agent states.

2 Likes