Skip to main content

Agent sessions

When each agent signed in to and out of a call queue or hunt group, and when they paused. This is the same data as the portal's User Events report.

Which endpoint​

GET /queues/agent-sessions, with the reports:read scope.

Each row is one session: a sign-in paired with its sign-out. A row tells you who the agent was (userId, userName, extension), which queue or hunt group it was, when it started and ended, and how long it lasted (durationSeconds).

typeWhat it means
queueThe agent was signed in to a call queue (queueId, queueName)
huntgroupThe agent was signed in to a hunt group (huntgroupId, huntgroupName)
pauseThe agent paused (was away): they turned on do not disturb on their line (line)

How far back​

History starts on 2024-11-18. Nothing earlier was recorded.

One request covers up to 31 days. start is required; end defaults to now. For a longer stretch, ask one window at a time — the window is [start, end), so back-to-back windows never return the same session twice.

Pauses are included​

Pause/away time comes back as sessions with type: "pause", in the same list as the queue and hunt group sessions. To get only pauses, send types=pause; to leave them out, send types=queue,huntgroup.

No extra setup​

There is nothing to switch on for the account. You need:

  1. An API key (or OAuth token) with the reports:read scope.
  2. A role that can see the report. For a key, that is the role of its run-as user (admin center → Integrations → API Keys → Runs as); for an OAuth token, the role of the person who approved the app. The role needs User Events turned on, and Call reports not set to Block.

The role also decides whose sessions you see: only the users, queues and hunt groups it can see in the portal. Unlike GET /users, a key here is narrowed by its run-as user's role, so the API shows exactly what that user sees in the portal's report. If you get fewer sessions than you expect, check the run-as user's role. A role without the report gets 403 permission_denied.

Example​

curl "https://api.account.telebroad.com/api/public/v1/queues/agent-sessions?start=2026-10-01T00:00:00Z&end=2026-10-08T00:00:00Z&limit=100" \
-H "Authorization: Bearer tbk_live_…"
{
"data": {
"start": "2026-10-01T00:00:00Z",
"end": "2026-10-08T00:00:00Z",
"sessions": [
{
"type": "queue",
"queueId": 812,
"queueName": "Support",
"userId": 481920,
"userName": "Dana Spencer",
"extension": "204",
"line": "acme-204",
"destinationType": "phone",
"destinationNumber": "acme-204",
"startTime": "2026-10-07T21:14:03Z",
"endTime": null,
"durationSeconds": null
},
{
"type": "pause",
"userId": 481920,
"userName": "Dana Spencer",
"extension": "204",
"line": "acme-204",
"startTime": "2026-10-07T17:30:12Z",
"endTime": "2026-10-07T17:45:40Z",
"durationSeconds": 928
},
{
"type": "queue",
"queueId": 812,
"queueName": "Support",
"userId": 481933,
"userName": "Sam Ortiz",
"destinationType": "forward",
"destinationNumber": "13475550123",
"startTime": "2026-10-07T13:00:05Z",
"endTime": "2026-10-07T13:00:09Z",
"durationSeconds": 4
}
],
"total": 3,
"limit": 100,
"offset": 0
}
}

Filter with users, queues or huntgroups (comma-separated ids) and types. Sessions come newest first. To page, raise offset and send the same end on every page — copy data.end from the first response — so the window does not move while you page.

Short sessions​

Every session is kept, however short. A sign-in followed by a sign-out a few seconds later comes back as its own row, like the 4-second one above. A durationSeconds of 0 means the agent signed out in the same second. Exact duplicate sign-in records are returned once.

Agents still signed in​

A session with no sign-out yet has endTime: null and durationSeconds: null (the first row above). Both fields are always present, so you never have to guess whether one was left out.

null can also mean the sign-out was never recorded: if the agent's next event on that queue, hunt group or line is another sign-in, the earlier session has no end. It is never paired with a later sign-out. Hunt groups record few sign-outs, so most hunt group sessions have no end.

A session belongs to the window it started in. One that started before start is not returned, even if the agent was still signed in during your window; one that started inside it comes back with its real end, even when that end is after end. To catch an agent who signed in earlier, start your window earlier.