Hit a snag trying to pull agent state history for the last 24 hours. The endpoint seems to exist but keeps returning an empty array [].
Using POST /api/v2/analytics/conversations/details/query with the following body:
{
"groupBy": ["agentId"],
"interval": "P1D",
"select": [
{"name": "agentId"},
{"name": "stateId"},
{"name": "stateName"}
],
"where": [
{"path": "dateInterval", "type": "dateInterval", "to": "2023-10-27T00:00:00.000Z", "from": "2023-10-26T00:00:00.000Z"}
]
}
Status code is 200. No errors. Just empty. Tried adding stateName to the groupBy. Same result. Checked the UI. Data is definitely there. Agents were logged in. States changed.
Is conversations/details the wrong endpoint for state history? Or is the dateInterval filter syntax wrong? The docs are sparse on this specific metric.
Here is the raw response header:
X-Request-Id: abc-123-def
Any idea what I’m missing?
You’re mixing up the data models here. The conversations/details/query endpoint is designed for transactional conversation data, not for historical agent state tracking. Agent states are managed by the Interaction Management or Workforce Management systems, and they don’t live in the conversation detail store in a way that supports this specific query structure. That’s why you’re getting an empty array. The endpoint doesn’t error out because the syntax is valid, but there’s simply no data matching that criteria in that table.
To get agent state history, you need to hit the specific analytics endpoint for agent performance or interaction history. If you want a detailed breakdown of states over time, POST /api/v2/analytics/agents/details/query is usually the right path. You’ll need to adjust your select array to pull stateId and stateName from the agent object, not the conversation object.
Here’s how that request body should look:
{
"groupBy": ["agentId"],
"interval": "P1D",
"select": [
{"name": "agentId"},
{"name": "agent.name"},
{"name": "stateId"},
{"name": "stateName"},
{"name": "duration"}
],
"where": [
{"path": "dateInterval", "type": "dateInterval", "value": "P1D"}
]
}
Make sure your OAuth token has the analytics:agent:view scope. Without it, you might get a 403, but if it’s just empty, it’s definitely the wrong endpoint. Also, keep in mind that “state” here refers to the interaction state (like Available, Busy, Offline) as recorded by the platform. If you’re looking for custom presence states or WFM-specific statuses, you might need to dig into the WFM API instead. The analytics API aggregates this data, so there can be a slight delay. Don’t expect real-time state changes here. It’s batched for reporting.
Spot on, . I ran into that same brick wall last week when trying to build a custom dashboard for agent availability. The conversations/details endpoint is strictly for interaction-level metrics, so it’s not going to hold the granular state history you need.
You actually want to hit the POST /api/v2/analytics/interactions/details/query endpoint instead. It’s under the interactions path, not conversations, and it handles the agentState data model correctly. Here’s the payload that finally got me results:
{
"groupBy": ["agentId", "stateId"],
"interval": "P1D",
"select": [
{ "name": "agentId" },
{ "name": "stateId" },
{ "name": "stateName" },
{ "name": "duration" }
],
"where": [
{ "path": "dateInterval", "type": "dateInterval", "from": "2023-10-25T00:00:00.000Z", "to": "2023-10-26T00:00:00.000Z" },
{ "path": "agentState.name", "type": "string", "value": "Available" }
]
}
Make sure you’re using the correct OAuth scope too. analytics:interaction:view is usually what you need here. If you’re still seeing empty arrays, double-check the date range format. Genesys is pretty strict about ISO 8601, and mixing up UTC and local time zones can kill the query instantly. Also, keep an eye on the interval parameter. If you set it to P1D but your query spans multiple days, you might need to adjust how you’re grouping the data.
Watch out for the interval parameter. If you set it to P1D on an interactions query, the engine aggregates everything into a single bucket, which often strips the granular state transitions you’re looking for. Try switching to PT1H or smaller to actually see the history.