GET /queues/agent-sessions
List agent sign-in and pause sessions
The agents' sign-in history: each time an agent logged in to and out of a call queue or hunt group, and each time they paused (turned on do not disturb on their line). One row per session, newest start first. This is the portal's User Events report.
| Scope | reports:read |
| Role permission | User Events on, and Call reports not set to Block; then only the users, queues and hunt groups the role can see |
| Cost | Free |
The role always applies — for API keys too. A key is narrowed by
the role of its run-as user, an OAuth token by the role of the
person who approved the app. Sessions of users, queues or hunt groups
that role cannot see are left out. A role without User Events, or
with Call reports → Block, gets 403 permission_denied.
History starts on 2024-11-18. Nothing earlier was recorded.
The window is required. start is required; end defaults to now.
Both take RFC 3339 or unix seconds, and may be at most 31 days
apart. The window is half-open, [start, end), so back-to-back windows
never return a session twice. For longer history, walk window by window.
A session belongs to the window it started in. One that started
before start is not returned, even if it was still running inside
the window. One that started inside the window comes back with its real
end, even when that end is after end.
When paging, send the same end on every page. Without end, each
request uses its own "now" and the pages slide. The response echoes the
window it applied — pass data.end back as end.
Short sessions are kept. A session of a few seconds, or 0 (signed
out in the same second), is a real session. Exact duplicate sign-in
records are returned once.
No end means still signed in — or the sign-out was never recorded.
endTime and durationSeconds are then null. A session ends at the
agent's next event on the same queue, hunt group or line if that event
is a sign-out; if it is another sign-in, the earlier session has no
end. Hunt groups record few sign-outs, so most hunt-group sessions have
no end.
Query parameters
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
start | string | yes | 2026-10-01T00:00:00Z | Start of the window, included — RFC 3339 or unix seconds. Sessions that started at or after this moment. Data starts on 2024-11-18. |
end | string | no | 2026-10-08T00:00:00Z | End of the window, not included — RFC 3339 or unix seconds. Defaults to now. At most 31 days after start. |
users | string | no | 481920,481933 | Only these agents — user ids from GET /users, comma-separated. |
queues | string | no | 812 | Only these queues — queue ids, comma-separated. Cannot be combined with huntgroups. With types, types must include queue. |
huntgroups | string | no | 305 | Only these hunt groups — hunt group ids, comma-separated. Cannot be combined with queues. With types, types must include huntgroup. |
types | string | no | queue,pause | Only these kinds of session, comma-separated: queue, huntgroup, pause. Omit for all three. |
limit | integer | no | — | Page size. An out-of-range value is a 400 rather than a silent clamp. |
offset | integer | no | — | How many results to skip before this page, for paging. Defaults to 0. |
Responses
200
A page of sessions, newest start first.
| Field | Type | Description |
|---|---|---|
start | string (RFC 3339) | Start of the window applied, included, in whole seconds (a fractional start is rounded up). |
end | string (RFC 3339) | End of the window applied, not included: the end you sent, or the time of the request when you sent none. Pass it back as end when paging so every page reads the same window. |
sessions | object[] | The sessions on this page, newest start first. |
sessions[].type | queue | huntgroup | pause | queue or huntgroup — signed in to one. pause — the agent turned on do not disturb on their line (paused / away). |
sessions[].queueId | integer | The queue of a queue session. |
sessions[].queueName | string | The queue's name. Missing if the queue has since been deleted. |
sessions[].huntgroupId | integer | The hunt group of a huntgroup session. |
sessions[].huntgroupName | string | The hunt group's name. Missing if it has since been deleted. |
sessions[].userId | integer | The agent — matches id in GET /users. Missing when the agent's line could not be matched to a user when the event was recorded. |
sessions[].userName | string | The agent's name, or username when no name is set. |
sessions[].extension | string | The internal extension of the agent's line, when the session is on a line (a pause, or a queue / hunt-group sign-in to a phone). |
sessions[].line | string | The agent's line: the line paused for a pause session, or the line signed in for a queue / hunt-group session to a phone. Missing for sign-ins that forward to an outside number. |
sessions[].destinationType | string | How the queue or hunt group reaches the agent: phone (a line), forward (an outside number) or sipuri. Missing for pause. |
sessions[].destinationNumber | string | The line or number the queue or hunt group rings. |
sessions[].startTime | string (RFC 3339) | When the agent signed in (or paused), UTC. |
sessions[].endTime | string (RFC 3339) | When they signed out (or un-paused), UTC. Always present: null while still signed in, or when the sign-out was never recorded. |
sessions[].durationSeconds | integer | endTime minus startTime, in seconds. null exactly when endTime is null. 0 is a real session that ended in the same second. |
total | integer | How many sessions match the filters in the window, across all pages. |
limit | integer | The page size applied. |
offset | integer | How many matching sessions were skipped before this page. |
{
"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
}
}
Errors
| Status | Meaning |
|---|---|
400 | invalid_request — a missing or malformed field, an unknown enum value, or an unknown field in the body. Nothing was charged. |
401 | unauthenticated — no credential, or one that is invalid, revoked or expired. The WWW-Authenticate header names the scope the endpoint wanted. |
403 | Two different failures share this status; the type field tells them apart — insufficient_scope (the credential lacks the scope) or permission_denied (the scope is fine, but the user's role lacks the permission). |
500 | internal_error — something failed on our side, not with your request. Safe to retry. |
See Errors for the full catalog and what to do about each.
Example
curl -X GET 'https://api.account.telebroad.com/api/public/v1/queues/agent-sessions?start=2026-10-01T00%3A00%3A00Z&end=2026-10-08T00%3A00%3A00Z&users=481920%2C481933&queues=812&huntgroups=305&types=queue%2Cpause' \
-H "Authorization: Bearer $TB_KEY"