CXone GET /agents/states returns empty array for logged in agent

NICE CXone API & Integrations
1

Calling the CXone REST endpoint GET /api/v2/agents/states/{agentId} returns 200 OK but the response body contains an empty array []. The agent is definitely logged in and active in the WFM dashboard. I’ve checked the auth token and it has the correct wem scope. Here is the raw response:

{
 "code": 200,
 "data": []
}

Is there a specific filter parameter I’m missing?

2

The issue usually isn’t the endpoint itself but rather how you’re fetching the agent ID or the state history window. The /api/v2/agents/states/{agentId} endpoint returns the history of state changes, not the current live state. If the agent just logged in and hasn’t changed states, or if you’re querying a window with no events, you get an empty array. It’s also worth checking if the {agentId} you’re passing is the internal CXone agent ID (UUID) and not the user’s email or extension. The API is strict about that.

Here’s how I typically handle this in our custom application to get the actual current state, which is usually what people actually need:

// First, get the current agent's status using the Agent Details API
const agentDetailsResponse = await cxone.agents.getAgentDetails(agentId);

// Extract the current state from the agentDetailsResponse.data object.
const currentState = agentDetailsResponse.data.currentState;

// If you absolutely need history, ensure you pass a valid range
const historyParams = {
 pageSize: 10,
 pageNumber: 1,
 // Ensure the time range covers recent activity
 startTime: '2023-10-01T00:00:00Z'
};
const history = await cxone.agents.getAgentStateHistory(agentId, historyParams);

Also, double-check your scopes. wem is for workforce management editing. Reading agent states usually requires agent:state:read or a similar permission depending on your organisation’s security policies. If the agent is “logged in” but hasn’t explicitly set a state (like “Available” or “Busy”), the state history might be sparse. Remember to comply with GDPR Article 5 regarding data minimisation; only request the agent states necessary for your application’s purpose.

I’d recommend focusing on the Agent Details API for real-time status. It’s cleaner and avoids the pagination complexities of the history endpoint. If that still returns nothing, your agent ID is likely incorrect. Log the UUID you’re using and compare it against the agent’s profile within the CXone Control Panel. The ID in the URL is the one the API expects. Verify the agent’s data protection settings in the CXone admin portal to ensure you have the appropriate permissions to access their state information.

2 Likes