GET /agents/states returns empty array despite active session

Is there a specific scope requirement for the GET /api/v2/agents/states endpoint that I’m missing? I’ve got a custom integration running in Mexico City time, pulling agent status for a dashboard. The auth token is valid, granted via Client Credentials flow with full admin scopes.

The agent is definitely logged in. I can see the green dot in the CXone UI. I can even see the session in the WebSocket stream. But when I hit the REST endpoint, I get back an empty array []. No error, no 401, just 200 OK and nothing in the body.

Here’s the cURL equivalent:

curl -X GET "https://api.mypurecloud.com/api/v2/agents/states?divisionId=main" \
 -H "Authorization: Bearer <valid_token>"

I’ve tried passing the divisionId query param. I’ve tried omitting it. Same result. I’m assuming this is a caching issue or maybe the endpoint only returns states for agents logged into specific channels? The docs are thin on this. Any ideas why the REST API is blind to the active session?

You’re probably hitting the scope limit. Client Credentials gives you org-level data, not user-level sessions. You need to use the user’s OAuth token with agent:read scope.

// Don't use app token here
var config = PlatformConfiguration.Builder().WithClientCredentials(clientId, clientSecret).Build();
// Switch to user context for session data

Docs say it clearly.