Skip to main content

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.

Scopereports:read
Role permissionUser Events on, and Call reports not set to Block; then only the users, queues and hunt groups the role can see
CostFree

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​

NameTypeRequiredExampleDescription
startstringyes2026-10-01T00:00:00ZStart of the window, included — RFC 3339 or unix seconds. Sessions that started at or after this moment. Data starts on 2024-11-18.
endstringno2026-10-08T00:00:00ZEnd of the window, not included — RFC 3339 or unix seconds. Defaults to now. At most 31 days after start.
usersstringno481920,481933Only these agents — user ids from GET /users, comma-separated.
queuesstringno812Only these queues — queue ids, comma-separated. Cannot be combined with huntgroups. With types, types must include queue.
huntgroupsstringno305Only these hunt groups — hunt group ids, comma-separated. Cannot be combined with queues. With types, types must include huntgroup.
typesstringnoqueue,pauseOnly these kinds of session, comma-separated: queue, huntgroup, pause. Omit for all three.
limitintegerno—Page size. An out-of-range value is a 400 rather than a silent clamp.
offsetintegerno—How many results to skip before this page, for paging. Defaults to 0.

Responses​

200​

A page of sessions, newest start first.

FieldTypeDescription
startstring (RFC 3339)Start of the window applied, included, in whole seconds (a fractional start is rounded up).
endstring (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.
sessionsobject[]The sessions on this page, newest start first.
sessions[].typequeue | huntgroup | pausequeue or huntgroup — signed in to one. pause — the agent turned on do not disturb on their line (paused / away).
sessions[].queueIdintegerThe queue of a queue session.
sessions[].queueNamestringThe queue's name. Missing if the queue has since been deleted.
sessions[].huntgroupIdintegerThe hunt group of a huntgroup session.
sessions[].huntgroupNamestringThe hunt group's name. Missing if it has since been deleted.
sessions[].userIdintegerThe 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[].userNamestringThe agent's name, or username when no name is set.
sessions[].extensionstringThe 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[].linestringThe 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[].destinationTypestringHow the queue or hunt group reaches the agent: phone (a line), forward (an outside number) or sipuri. Missing for pause.
sessions[].destinationNumberstringThe line or number the queue or hunt group rings.
sessions[].startTimestring (RFC 3339)When the agent signed in (or paused), UTC.
sessions[].endTimestring (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[].durationSecondsintegerendTime minus startTime, in seconds. null exactly when endTime is null. 0 is a real session that ended in the same second.
totalintegerHow many sessions match the filters in the window, across all pages.
limitintegerThe page size applied.
offsetintegerHow 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​

StatusMeaning
400invalid_request — a missing or malformed field, an unknown enum value, or an unknown field in the body. Nothing was charged.
401unauthenticated — no credential, or one that is invalid, revoked or expired. The WWW-Authenticate header names the scope the endpoint wanted.
403Two 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).
500internal_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"

Try it in the playground →