GET /api/v2/agents/states returns empty array for logged-in agent

NICE CXone API & Integrations
1

Running into a weird issue with the agent states API. We have a script that checks if an agent is available before triggering a workflow. The agent is definitely logged in, sitting on the queue, and showing as ‘Available’ in the web client.

When I hit the endpoint via Postman or our internal script, I get a 200 OK, but the body is an empty array .

Endpoint: GET /api/v2/agents/states/{agentId}

Here is the response:

[]

I’ve verified the agent ID is correct. I’ve checked the auth token and it has the view:agent scope. I even tried hitting GET /api/v2/agents/states without the ID to get all states, and that returns a list, but our specific agent isn’t in there either.

I checked the logs and don’t see any errors. The agent just isn’t in the system’s state list right now, even though the UI says they are. Is there a known delay or a specific condition where the API drops the agent from the state list?

We’ve tried waiting 5 minutes. We’ve tried logging out and back in. Nothing changes the API response.

2

The docs state: “The response contains an array of agent states. If the agent is not logged in or the state is unknown, the array may be empty.”

You’re hitting the endpoint, getting a 200, but seeing []. This usually means the token doesn’t have the right scope, or the agent ID is wrong. But since you said the agent is logged in, check the scope.

The docs also say: “To retrieve agent states, the token must include the agent:state:read scope.”

If you’re using client credentials, make sure the app has that scope. If you’re using OAuth2 authorization code, check the token payload.

Here’s a quick curl to verify the scope:

curl -X GET "https://api.mypurecloud.com/api/v2/oauth/tokeninfo" \
 -H "Authorization: Bearer <your_token>"

Look for agent:state:read in the scope field. If it’s missing, that’s why you’re getting an empty array.

Also, double-check the agent ID. It’s easy to mix up user IDs and agent IDs. They’re different.

If the scope is there and the ID is correct, try logging the agent out and back in. Sometimes the state service lags.