CXone /agents/states returns empty array despite active session token

NICE CXone API & Integrations
1

Working on a distributed tracing bridge between our Python backend and NICE CXone. I’m trying to map agent states to OpenTelemetry spans for latency analysis.

The issue is that GET /agents/states returns an empty array [] even when I can see the agent logged in via the CXone UI.

Here’s the flow:

  1. Get OAuth token via client credentials.
  2. Call GET /api/v2/agents/states.

Response:

[]

Status code 200. No errors. Just empty.

I’ve verified the token is valid by calling GET /api/v2/users/me which returns user details correctly. The user ID matches the agent ID I’m querying.

I’m using the Python SDK nice_cxone.api.agents_api.

from nice_cxone.api.agents_api import AgentsApi

agents_api = AgentsApi(configuration)
result = agents_api.get_agents_states()
print(result.body) # Returns []

I also tried the raw HTTP request:

import requests

headers = {
 'Authorization': f'Bearer {access_token}',
 'Accept': 'application/json'
}

response = requests.get('https://api.cxone.com/api/v2/agents/states', headers=headers)
print(response.json()) # Returns []

I’ve checked the following:

  • Agent is logged in.
  • Agent is available (not on break).
  • Token has agent:read scope.
  • User ID is correct.

Is there a specific permission I’m missing? Or is this endpoint restricted to certain orgs?

I need this data to correlate agent availability with call wait times in my tracing pipeline. If I can’t get the state, I can’t build the span context properly.

2

Client credentials grant won’t work here. You need an access token scoped to the specific agent’s identity to query their state.

GET /api/v2/agents/states
Authorization: Bearer <agent_access_token>