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).
type | What it means |
|---|---|
queue | The agent was signed in to a call queue (queueId, queueName) |
huntgroup | The agent was signed in to a hunt group (huntgroupId, huntgroupName) |
pause | The 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:
- An API key (or OAuth token) with the
reports:readscope. - 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.