Get work items By work session

get/v1/routing/work-sessions/{id}/work-items
Requires any one of these rolesAbout roles
org.permission.work_session.readorg.permission.routing.read
Legacyorg.user.routing.read

The API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.

Retrieves the list of work items in a work session.

About this resource

Work sessions

A work session is one agent's shift in routing, from the moment they first set a routing status until they go offline. It tracks their status, how much capacity they have left, the work items they hold, and how long they spent in each status.

Routing decides which agent gets each conversation, and it only considers agents who have a live work session. A session is created the first time an agent sets a routing status, usually by signing in to routing in the agent desktop. It ends when they switch to a status of type offline: Kustomer sets signedOutAt, active becomes false, and the session is read-only from then on. The next status change starts a new session, so each user has at most one current session and a history of past ones.

Status and routability

Every session points to a routing user status, such as "Available", "Lunch" or "Training". Admins define those statuses; each one has a statusType, and that type is what routing acts on:

statusType Meaning
available Ready for new work. The only type that can receive routed items.
busy Set by the system while an agent is on a call or in wrap-up. Counts toward queue staffing, but receives nothing new.
unavailable Signed in but not taking work, such as on a break.
offline Signed out. Setting it ends the session.

routable is true only while all three hold: the status type is available, there is capacity left, and no item is waiting for the agent to accept it.

Channel availability

Agents who take calls can be kept on the phones, or kept off them, with channelAvailability:

channelAvailability Routing offers the session
all-channels Work from every channel. The default, and what sessions without a value get.
voice-only Voice work items only.
non-voice Everything except voice.

The restriction applies only while the org's channel availability mode is on. It's off by default, and an admin with settings permissions turns it on with PUT /v1/settings/routing/general/channelAvailabilityMode and { "value": true }. While it's on, listing a queue's sessions with channel leaves out non-voice sessions for voice, and voice-only sessions for every other channel. The value is case-sensitive, so send voice in lowercase. app alone doesn't filter.

Set voice-only or non-voice on PUT with the rest of the session update. The request fails with 422 if the mode is off, or if the session's team has no voice-capable queue. Send all-channels to lift the restriction.

Capacity

Capacity is how much work an agent can hold at once, set in team routing settings. Each assigned work item uses capacity equal to its itemSize, and a paused item uses none. totalCapacity and capacityRemaining give the overall picture, and capacity breaks it down by work item priority as { priority, limit, remaining }. capacityStatus summarizes it as idle, not-at-capacity or at-capacity.

Time tracking

Sessions are the source for agent utilization reporting. totalAvailable, totalUnavailable and totalBusy each hold time (milliseconds spent in that status type), businessTime (the same, counted only within the team's business hours) and statusAt (when the agent last entered it). The …IdleCapacity, …NotAtCapacity and …AtCapacity variants split that time by how loaded the agent was, and totalTimeByStatus breaks it down by individual status ID. handledItemCount and handledConversationCount count the work completed in the session.

Which endpoint to use

To Call
Read or change the signed-in user's own session GET or PUT /v1/routing/work-sessions/current
See whether a specific agent is working right now GET /v1/routing/users/{id}/work-sessions/current
Report on an agent's past shifts GET /v1/routing/users/{id}/work-sessions
Find who is staffing a queue GET /v1/routing/queues/{id}/work-sessions, with routable=true for agents who can take work now
List sessions across the org GET /v1/routing/work-sessions, with active=true for current sessions only
Read one session, past or current GET /v1/routing/work-sessions/{id}
See what an agent is holding right now GET /v1/routing/work-sessions/current/work-items for yourself, or GET /v1/routing/work-sessions/{id}/work-items for any session
Change another agent's status, as a supervisor PUT /v1/routing/work-sessions/{id}
Turn voice-only and non-voice sessions on or off for the org GET or PUT /v1/settings/routing/general/channelAvailabilityMode

To change a status, send the routing user status ID as status. Sending team moves the agent to that team's queues and capacity rules, and channelAvailability restricts which channels they're offered. PUT /v1/routing/work-sessions/{id} also accepts rev, the revision you last read; if the session changed since then, the request fails with 409 Conflict, so read it again and retry. Updating a session that has already ended fails with 400, and a channelAvailability the org or team can't use fails with 422.

Path parameters

idstringrequired
Example "5f184e74c61792001af42e49"

Responses

OK

array<object>required