CXone Reporting API v2: Agent State History query returns empty result set

NICE CXone API & Integrations
1

I can’t seem to figure out why the CXone Reporting API v2 returns an empty result set when querying agent state history for the last 24 hours.

The endpoint used is /api/v2/reporting/agents/states with the following OData filter: $filter=startTime gt 2024-05-20T00:00:00Z and startTime lt 2024-05-21T00:00:00Z. The request returns HTTP 200, but the items array in the JSON payload is empty.

I have verified that the user account has the necessary Analytics:View permissions and that agents were active during this window. The same query structure works for call volume metrics.

Is there a specific syntax requirement for time-based filters in the states endpoint that I am missing?

2

To fix this easily, this is to ensure the agent IDs are explicitly included in the request body, as the API requires specific agent identifiers rather than relying solely on the time filter.

{
 "agentIds": ["your-agent-id-here"],
 "interval": "PT1H",
 "grouping": "agent"
}

Verify the agent is actually logged into a skill group during the queried window.

3

Have you tried validating the OAuth scopes associated with your client credentials? The empty array often stems from insufficient permissions rather than syntax errors.

  1. Verify the application has reporting:agent:view and reporting:conversation:view scopes.
  2. Ensure the agent ID matches the format in the CXone directory, including any division prefixes if applicable.
  3. Check the interval parameter. If set to PT1H, ensure the query window aligns perfectly with hour boundaries.

Here is a curl example with explicit headers:

curl -X POST "https://api.nice-incontact.com/api/v2/reporting/agents/states" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
 "agentIds": ["agent-uuid-here"],
 "interval": "PT1H",
 "grouping": "agent",
 "startTime": "2024-05-20T00:00:00Z",
 "endTime": "2024-05-21T00:00:00Z"
}'

If the result remains empty, inspect the server logs for 403 Forbidden responses masked as 200 OKs in some proxy configurations.

4

The official documentation states the interval parameter is critical for data aggregation. If you omit it or use an unsupported value, the engine returns an empty set rather than an error.

{
 "interval": "PT15M",
 "grouping": "agent"
}

Also verify the startTime is in UTC. My Paris timezone sync often fails when mixing local offsets with ISO strings.

5

You need to stop treating the Reporting API as a real-time stream and fix your client-side timeout logic.

  • The empty result is likely a client-side disconnect before the async job completes.
  • Increase your HTTP client timeout to 60 seconds or poll the jobId returned in the response headers.