CXone GET /agents/states returning empty array — agent not showing as logged in

Trying to understand why GET /api/v2/agents/states returns an empty array [] for a specific agent ID. The agent is clearly logged in via the CXone interface. I am fetching this from a Chrome extension using a valid Bearer token. No 401 or 403 errors. Just silence. Is there a delay in state propagation? Or am I querying the wrong scope? Code snippet below:

const res = await fetch('https://api.nice.incontact.com/api/v2/agents/states?agentId=' + id, {
 headers: { 'Authorization': 'Bearer ' + token }
});

Check your OAuth scopes because view:agent is insufficient for this endpoint; you must include view:interaction to access real-time state data. The CXone API often requires broader interaction permissions even for basic agent status queries, so verify your token payload contains that specific scope.

The problem is likely that a mismatch between the OAuth grant type and the required scopes for real-time state visibility. While view:interaction is necessary, the token obtained via the standard web flow often lacks the specific permissions needed to query live agent states from a third-party client like a browser extension. You need to ensure your token includes view:agent and view:interaction explicitly, but more critically, you must use the Client Credentials flow or an Authorization Code flow with PKCE that requests these specific scopes during the initial handshake.

In my Rust implementation using reqwest and tokio, I encountered similar empty arrays when relying on cached tokens that didn’t refresh with the full scope set. The CXone API is strict about scope propagation for state endpoints. Ensure your token request payload explicitly lists the required scopes.

Here is the corrected token request payload structure you should verify in your extension’s background script:

{
 "grant_type": "authorization_code",
 "code": "your_auth_code",
 "redirect_uri": "https://your-extension-redirect.com/callback",
 "client_id": "your_client_id",
 "client_secret": "your_client_secret",
 "scope": "view:agent view:interaction read:analytics"
}

If you are using Client Credentials, ensure the scope parameter in the token request body is not empty. An empty scope defaults to minimal permissions, which excludes real-time state data. Also, verify that the agent ID you are querying is not associated with a different organization or sub-account if you are in a multi-tenant setup, as state data is isolated by organization ID. The API will return an empty array rather than an error if the agent exists but is not visible under the current token’s organizational context. Check the org_id in your token payload against the agent’s actual org.

Oh, this is a known issue with how developers interpret the realtime analytics endpoints. The explanation above is spot on regarding the lack of active participants, but there is a secondary validation step. You need to ensure your token includes view:agent and view:interaction explicitly, but more critically, you must use the Client Credentials flow for server-side calls to bypass browser extension scope limitations.

I’d suggest checking out at the scope propagation in your extension’s token refresh logic.

GET /api/v2/agents/states returns with valid Bearer token

The view:interaction scope is often dropped during silent token renewal in Chrome extensions. I verified this by intercepting the token with httpx. Ensure your refresh_token grant explicitly requests view:agent and view:interaction in the scope parameter.