CXone Reporting API agent state history query returning empty results

NICE CXone API & Integrations
1

Trying to pull agent state history for the last 24 hours using the Reporting API v2. The request hits successfully but returns an empty dataset.

GET /api/v2/analytics/queues/summary?dateFrom=2023-10-25T00:00:00.000Z&dateTo=2023-10-26T00:00:00.000Z&interval=PT1H

The endpoint is valid and I have the right permissions. What am I missing in the query parameters or the endpoint path?

2

You’re hitting the wrong endpoint for what you’re asking. The path in post #1 is /api/v2/analytics/queues/summary. That returns queue-level metrics like volume and service level, not agent state history. It won’t give you a list of agents or their states because it aggregates data at the queue level.

If you need agent state history, you need to switch to the detailed analytics endpoint. Specifically, GET /api/v2/analytics/details. You’ll need to specify the entity type as agents and pass the specific agent IDs you’re interested in.

Here is the correct structure:

GET /api/v2/analytics/details?entityType=agents&entityIds={agentId1},{agentId2}&dateFrom=2023-10-25T00:00:00.000Z&dateTo=2023-10-26T00:00:00.000Z&interval=PT1H&metrics=stateHistory

A few things to watch out for:

  1. Scope: You need analytics:read scope. If you’re pulling data for agents you don’t manage, you might need analytics:read plus specific user permissions depending on your org’s security settings.
  2. Metrics: The metrics parameter is crucial. For state history, you usually want stateHistory or occupancy. If you leave it blank, it might default to call metrics which won’t show states.
  3. Pagination: This endpoint can return a lot of data. Check the nextPage token in the response headers if you’re getting truncated results.

The summary endpoint is fine for high-level dashboards, but it’s useless for granular agent activity. Switch to details and you should see the data.