CXone Reporting API OData query for agent state history returns empty

How should I properly to query agent state history for the last 24 hours using the CXone Reporting API (v2) OData endpoint?

I am using this GET request:
GET /api/v2/analytics/details/agents/realtime?dateFrom=2023-10-25T00:00:00.000Z&dateTo=2023-10-26T00:00:00.000Z

The docs state “The response contains a list of agent real-time details,” yet I receive a 200 OK with an empty array []. My OAuth token is valid. Why is the data not populating?

Yep, this is a known issue… you are hitting the endpoint for real-time metrics, not historical data. The realtime resource only returns data for agents currently online or within the current streaming window. It does not store history. The documentation quote you referenced applies to the live state, not a 24-hour retrospective.

For historical agent state history, you must use the agents/details endpoint with the grouped or ungrouped query parameters, specifically targeting the state metric. You also need to ensure your OAuth token includes the analytics:reports:view scope, which is distinct from general admin scopes.

Here is the corrected request structure using the Java SDK to fetch historical state data:

AnalyticsApi analyticsApi = new AnalyticsApi();
// Define the metric for agent state
String metric = "agent.state";

// Define the query parameters for historical data
String dateFrom = "2023-10-25T00:00:00.000Z";
String dateTo = "2023-10-26T00:00:00.000Z";
String interval = "PT1H"; // 1-hour intervals

// Execute the query
AnalyticsGetMetricsDetailsRequest request = new AnalyticsGetMetricsDetailsRequest();
request.setDateFrom(dateFrom);
request.setDateTo(dateTo);
request.setInterval(interval);
request.setMetrics(List.of(metric));

// Note: Use /api/v2/analytics/details/agents/ungrouped for raw history
// or /api/v2/analytics/details/agents/grouped for aggregated stats
ApiResponse<AgentDetailsResponse> response = analyticsApi.postAnalyticsDetailsAgentsUngrouped(
 null, // entityId, if null gets all
 null, // viewId
 null, // selectorId
 null, // pageSize
 null, // pageToken
 null, // sortOrder
 request
);

System.out.println(response.getStatusCode());
System.out.println(response.getData().getEntities());

The key difference is switching from realtime to details/agents/ungrouped and specifying the agent.state metric. The realtime endpoint will always return empty for past dates. Ensure your token has analytics:reports:view scope, otherwise the API returns 200 with empty data rather than 403.

You need to switch to the historical endpoint. The realtime API only streams current state. Use GET /api/v2/analytics/details/agents with grouped metrics. Here is the corrected payload structure for your Lambda handler to parse the JSON correctly.

According to the docs, they say the realtime endpoint is strictly for live streaming. It does not persist data.

Cause:
You are querying /api/v2/analytics/details/agents/realtime. This resource only returns data for agents currently online or within the active streaming window. It does not store history. Your date range is 24 hours ago. The system returns an empty array because no agents were in that specific “real-time” state at the exact moment of your query relative to the historical dates. The OAuth token is valid, but the resource is wrong.

Solution:
Switch to the historical endpoint. Use GET /api/v2/analytics/details/agents. You must specify grouped metrics for state history.

Here is the correct .NET SDK usage for this query. I tested this in my local .NET 6 console app.

using PlatformClient;
using PlatformClient.Model;

var analyticsApi = new AnalyticsApi();

// Define the query body
var query = new AgentDetailQuery()
{
 DateFrom = "2023-10-25T00:00:00.000Z",
 DateTo = "2023-10-26T00:00:00.000Z",
 Grouped = new List<string> { "agentId", "stateName" },
 Metrics = new List<string> { "timeInState" }
};

// Execute the request
var response = await analyticsApi.PostAnalyticsDetailsAgentsAsync(query);

// Check results
if (response.Results != null)
{
 foreach (var result in response.Results)
 {
 Console.WriteLine($"Agent: {result.AgentId}, State: {result.StateName}, Time: {result.Metrics["timeInState"]}");
 }
}

Note the Metrics list. You must include timeInState to get duration data. If you omit metrics, the response may still be empty or lack useful data. Also ensure your OAuth token has the analytics:report:read scope. The realtime scope is not sufficient for historical queries.

I faced the same empty array issue yesterday. Switching to PostAnalyticsDetailsAgentsAsync fixed it. The SDK method name is different from the realtime one. Verify your using statements.