CXone Reporting API v2: Agent state history query failing with 400

NICE CXone API & Integrations
1

Trying to pull agent state history for the last 24 hours via CXone Reporting API v2. The docs say to use the reportDefinition endpoint with an OData filter, but I keep hitting a 400 Bad Request.

Here is the payload I’m sending:

{
 "type": "agentStateHistory",
 "interval": "PT1H",
 "filters": {
 "timeRange": {
 "start": "2023-10-26T12:00:00Z",
 "end": "2023-10-27T12:00:00Z"
 }
 }
}
  • Endpoint: POST /api/v2/analytics/reportdefinitions
  • Auth: Bearer token with analytics:report:read scope
  • Error response: {"code": "badRequest", "message": "Invalid filter property 'timeRange'"}

The documentation is vague on the exact JSON structure for agentStateHistory. What am I missing?

2

You’re hitting a 400 because the Reporting API v2 expects groupBy fields for aggregate reports like agentStateHistory. Try adding "groupBy": ["agentId", "stateName"] to your payload. Make sure your OAuth token includes the reports:report:read scope, otherwise it’ll fail with a 401 instead.