Get work sessions by queue ID

get/v1/routing/queues/{id}/work-sessions

Requires any one of these rolesAbout roles

org.permission.queue.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 a paginated list of work sessions by queue ID.

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.

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}`

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. 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.

Path parameters

idstringrequired

Queue ID

Example "5f184e74c61792001af42e49"

Query parameters

pageinteger

Page number to return.

Example 1

pageSizeinteger

Number of records to return per page.

Example 100

routableboolean

When true, returns only routable work sessions.

Example true

statusTypestring

Filter by work session status type. Supported values are available, unavailable, busy, and offline.

One ofavailableunavailablebusyofflineExample "available"

channelstring

Filter queue work sessions by channel.

Example "voice"

appstring

Filter queue work sessions by app.

Example "kustomer"

Responses

objectrequired

array<object>required

Open in the API console

curl --request GET \
  --url 'https://api.kustomerapp.com/v1/routing/queues/5f184e74c61792001af42e49/work-sessions' \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"

{
  "meta": {
    "pageSize": 100,
    "page": 1
  },
  "links": {
    "self": "/v1/routing/queues/5dee362707e4c501dd8218fa/work-sessions?page=1&pageSize=100",
    "first": "/v1/routing/queues/5dee362707e4c501dd8218fa/work-sessions?page=1&pageSize=100",
    "prev": null,
    "next": null
  },
  "data": [
    {
      "id": "5dee362707e4c501dd821928",
      "type": "work_session",
      "attributes": {
        "routable": false,
        "statusType": "offline",
        "workItemCount": 0,
        "pausedWorkItemCount": 0,
        "signedInAt": "2019-12-09T11:55:19.767Z",
        "signedOutAt": "2019-12-09T11:55:19.767Z",
        "capacity": [
          {
            "priority": 1,
            "limit": 10,
            "remaining": 10
          },
          {
            "priority": 10,
            "limit": 2,
            "remaining": 2
          }
        ],
        "capacityRemaining": 10,
        "totalCapacity": 10,
        "handledItemCount": 0,
        "handledConversationCount": 0,
        "totalTimeByStatus": {
          "5dee362707e4c501dd8218f8": {
            "statusAt": "2019-12-09T11:55:19.767Z"
          }
        },
        "capacityStatus": "idle",
        "updatedAt": "2019-12-09T11:55:19.767Z",
        "modifiedAt": "2019-12-09T11:55:19.767Z",
        "createdAt": "2019-12-09T11:55:19.767Z",
        "rev": 1
      },
      "relationships": {
        "org": {
          "data": {
            "type": "org",
            "id": "55d7998f2d3f9f8800099aed"
          },
          "links": {
            "self": "/v1/orgs/55d7998f2d3f9f8800099aed"
          }
        },
        "user": {
          "data": {
            "type": "user",
            "id": "5dd7998f2d3f9f8800099aed"
          },
          "links": {
            "self": "/v1/users/5dd7998f2d3f9f8800099aed"
          }
        },
        "team": {
          "data": {
            "type": "team",
            "id": "55d79fff2d3f9f8800099aff"
          },
          "links": {
            "self": "/v1/teams/55d79fff2d3f9f8800099aff"
          }
        },
        "routingSettings": {
          "data": {
            "type": "team_routing_settings",
            "id": "5dee362707e4c501dd8218fe"
          },
          "links": {
            "self": "/v1/routing/settings/5dee362707e4c501dd8218fe"
          }
        },
        "status": {
          "data": {
            "type": "status",
            "id": "5dee362707e4c501dd8218f8"
          },
          "links": {
            "self": "/v1/routing/statuses/5dee362707e4c501dd8218f8"
          }
        },
        "modifiedBy": {
          "data": {
            "type": "user",
            "id": "5dd7998f2d3f9f8800099aed"
          },
          "links": {
            "self": "/v1/users/5dd7998f2d3f9f8800099aed"
          }
        },
        "queues": {
          "data": [
            {
              "type": "queue",
              "id": "5dee362707e4c501dd8218fa"
            }
          ]
        },
        "lastRevision": {
          "data": {
            "type": "work_session_revision",
            "id": "5dee362707e4c501dd821929"
          }
        }
      },
      "links": {
        "self": "/v1/routing/work-sessions/5dee362707e4c501dd821928"
      }
    },
    {
      "id": "5dee362707e4c501dd82192b",
      "type": "work_session",
      "attributes": {
        "routable": false,
        "statusType": "unavailable",
        "workItemCount": 0,
        "pausedWorkItemCount": 0,
        "signedInAt": "2019-12-09T11:55:19.787Z",
        "capacity": [
          {
            "remaining": 10,
            "limit": 10,
            "priority": 1
          },
          {
            "remaining": 2,
            "limit": 2,
            "priority": 10
          }
        ],
        "capacityRemaining": 10,
        "totalCapacity": 10,
        "handledItemCount": 0,
        "handledConversationCount": 0,
        "totalAvailable": {
          "statusAt": "2019-12-09T11:55:19.787Z",
          "businessTime": 75,
          "time": 75
        },
        "totalAvailableIdleCapacity": {
          "businessTime": 75,
          "time": 75
        },
        "totalUnavailable": {
          "statusAt": "2019-12-09T11:55:19.862Z"
        },
        "totalTimeByStatus": {
          "5dee362707e4c501dd8218f4": {
            "statusAt": "2019-12-09T11:55:19.787Z",
            "businessTime": 75,
            "time": 75
          },
          "5dee362707e4c501dd8218f7": {
            "statusAt": "2019-12-09T11:55:19.862Z"
          }
        },
        "capacityStatus": "idle",
        "updatedAt": "2019-12-09T11:55:19.862Z",
        "modifiedAt": "2019-12-09T11:55:19.862Z",
        "createdAt": "2019-12-09T11:55:19.787Z",
        "rev": 4,
        "lastRevision": {
          "handledItemCount": 0,
          "totalAvailable": {
            "statusAt": "2019-12-09T11:55:19.829Z"
          }
        }
      },
      "relationships": {
        "org": {
          "data": {
            "type": "org",
            "id": "55d7998f2d3f9f8800099aed"
          },
          "links": {
            "self": "/v1/orgs/55d7998f2d3f9f8800099aed"
          }
        },
        "user": {
          "data": {
            "type": "user",
            "id": "5dd7998f2d3f9f8800099aed"
          },
          "links": {
            "self": "/v1/users/5dd7998f2d3f9f8800099aed"
          }
        },
        "team": {
          "data": {
            "type": "team",
            "id": "55d79fff2d3f9f8800099aff"
          },
          "links": {
            "self": "/v1/teams/55d79fff2d3f9f8800099aff"
          }
        },
        "routingSettings": {
          "data": {
            "type": "team_routing_settings",
            "id": "5dee362707e4c501dd8218fe"
          },
          "links": {
            "self": "/v1/routing/settings/5dee362707e4c501dd8218fe"
          }
        },
        "status": {
          "data": {
            "type": "status",
            "id": "5dee362707e4c501dd8218f7"
          },
          "links": {
            "self": "/v1/routing/statuses/5dee362707e4c501dd8218f7"
          }
        },
        "modifiedBy": {
          "data": {
            "type": "user",
            "id": "5dd7998f2d3f9f8800099aed"
          },
          "links": {
            "self": "/v1/users/5dd7998f2d3f9f8800099aed"
          }
        },
        "queues": {
          "data": [
            {
              "type": "queue",
              "id": "5dee362707e4c501dd8218fa"
            }
          ]
        }
      },
      "links": {
        "self": "/v1/routing/work-sessions/5dee362707e4c501dd82192b"
      }
    },
    {
      "id": "5dee362707e4c501dd821922",
      "type": "work_session",
      "attributes": {
        "routable": false,
        "statusType": "offline",
        "workItemCount": 2,
        "pausedWorkItemCount": 1,
        "signedInAt": "2019-12-09T11:55:19.714Z",
        "signedOutAt": "2019-12-09T11:55:19.740Z",
        "capacity": [
          {
            "priority": 1,
            "limit": 10,
            "remaining": 9
          },
          {
            "priority": 10,
            "limit": 2,
            "remaining": 2
          }
        ],
        "capacityRemaining": 9,
        "totalCapacity": 10,
        "handledItemCount": 0,
        "handledConversationCount": 0,
        "totalAvailable": {
          "statusAt": "2019-12-09T11:55:19.714Z",
          "businessTime": 26,
          "time": 26
        },
        "totalAvailableNotAtCapacity": {
          "businessTime": 26,
          "time": 26
        },
        "totalTimeByStatus": {
          "5dee362707e4c501dd8218f4": {
            "statusAt": "2019-12-09T11:55:19.714Z",
            "businessTime": 26,
            "time": 26
          },
          "5dee362707e4c501dd8218f8": {
            "statusAt": "2019-12-09T11:55:19.740Z"
          }
        },
        "capacityStatus": "not-at-capacity",
        "updatedAt": "2019-12-09T11:55:19.740Z",
        "modifiedAt": "2019-12-09T11:55:19.740Z",
        "createdAt": "2019-12-09T11:55:19.714Z",
        "rev": 2
      },
      "relationships": {
        "org": {
          "data": {
            "type": "org",
            "id": "55d7998f2d3f9f8800099aed"
          },
          "links": {
            "self": "/v1/orgs/55d7998f2d3f9f8800099aed"
          }
        },
        "user": {
          "data": {
            "type": "user",
            "id": "5dd7998f2d3f9f8800099aed"
          },
          "links": {
            "self": "/v1/users/5dd7998f2d3f9f8800099aed"
          }
        },
        "team": {
          "data": {
            "type": "team",
            "id": "55d79fff2d3f9f8800099aff"
          },
          "links": {
            "self": "/v1/teams/55d79fff2d3f9f8800099aff"
          }
        },
        "routingSettings": {
          "data": {
            "type": "team_routing_settings",
            "id": "5dee362707e4c501dd8218fe"
          },
          "links": {
            "self": "/v1/routing/settings/5dee362707e4c501dd8218fe"
          }
        },
        "status": {
          "data": {
            "type": "status",
            "id": "5dee362707e4c501dd8218f8"
          },
          "links": {
            "self": "/v1/routing/statuses/5dee362707e4c501dd8218f8"
          }
        },
        "modifiedBy": {
          "data": {
            "type": "user",
            "id": "5dd7998f2d3f9f8800099aed"
          },
          "links": {
            "self": "/v1/users/5dd7998f2d3f9f8800099aed"
          }
        },
        "queues": {
          "data": [
            {
              "type": "queue",
              "id": "5dee362707e4c501dd8218fa"
            }
          ]
        },
        "lastRevision": {
          "data": {
            "type": "work_session_revision",
            "id": "5dee362707e4c501dd821923"
          }
        }
      },
      "links": {
        "self": "/v1/routing/work-sessions/5dee362707e4c501dd821922"
      }
    }
  ]
}

Long arrays and strings are shortened here. The full example is in the downloadable spec.