Get work sessions

get/v1/routing/work-sessions

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 a paginated list of work sessions.

Filtering

This endpoint supports optional filters for user, active status, and status type.

User (current user querying)

Add user=(true|false) in the query parameters with one of the following options:

true - Return current users work sessions
false - Return all users work sessions

Active

Add active=(true|false) in the query parameters with one of the following options:

true - Return current active work sessions
false - Return all work sessions

Status Type

Add statusType=[statusType] in the query parameters with one of the following options:

available - Available work sessions
unavailable - Unavailable work sessions
busy - Busy work sessions

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.

Query parameters

userboolean

User work sessions. true returns only current users work sessions. false returns only all users work sessions.

Example true

activeboolean

Active work sessions. true returns only active work sessions. false returns all work sessions.

Example true

statusTypestring

Status type. Options: available for available users, unavailable for unavailable users, busy for busy users, and offline for offline users.

One ofavailableunavailablebusyofflineExample "busy"

pageinteger

Page number to return.

Example 1

pageSizeinteger

Number of records to return per page.

Example 100

sortstring

Sort direction.

One ofascdescExample "desc"

Responses

objectrequired

array<object>required

Open in the API console

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

{
  "meta": {
    "pageSize": 100,
    "page": 1
  },
  "links": {
    "self": "/v1/routing/work-sessions?active=true&page=1&pageSize=100",
    "first": "/v1/routing/work-sessions?active=true&page=1&pageSize=100",
    "prev": null,
    "next": null
  },
  "data": [
    {
      "id": "5dee34bb431fd301ab0fcc2a",
      "type": "work_session",
      "attributes": {
        "routable": false,
        "statusType": "unavailable",
        "workItemCount": 0,
        "pausedWorkItemCount": 0,
        "signedInAt": "2019-12-09T11:49:15.025Z",
        "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:49:15.025Z",
          "businessTime": 84,
          "time": 84
        },
        "totalAvailableIdleCapacity": {
          "businessTime": 84,
          "time": 84
        },
        "totalUnavailable": {
          "statusAt": "2019-12-09T11:49:15.109Z"
        },
        "totalTimeByStatus": {
          "5dee34ba431fd301ab0fcbf3": {
            "statusAt": "2019-12-09T11:49:15.025Z",
            "businessTime": 84,
            "time": 84
          },
          "5dee34ba431fd301ab0fcbf6": {
            "statusAt": "2019-12-09T11:49:15.109Z"
          }
        },
        "capacityStatus": "idle",
        "updatedAt": "2019-12-09T11:49:15.109Z",
        "modifiedAt": "2019-12-09T11:49:15.109Z",
        "createdAt": "2019-12-09T11:49:15.025Z",
        "rev": 4,
        "lastRevision": {
          "handledItemCount": 0,
          "totalAvailable": {
            "statusAt": "2019-12-09T11:49:15.072Z"
          }
        }
      },
      "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": "5dee34ba431fd301ab0fcbfd"
          },
          "links": {
            "self": "/v1/routing/settings/5dee34ba431fd301ab0fcbfd"
          }
        },
        "status": {
          "data": {
            "type": "status",
            "id": "5dee34ba431fd301ab0fcbf6"
          },
          "links": {
            "self": "/v1/routing/statuses/5dee34ba431fd301ab0fcbf6"
          }
        },
        "modifiedBy": {
          "data": {
            "type": "user",
            "id": "5dd7998f2d3f9f8800099aed"
          },
          "links": {
            "self": "/v1/users/5dd7998f2d3f9f8800099aed"
          }
        },
        "queues": {
          "data": [
            {
              "type": "queue",
              "id": "5dee34ba431fd301ab0fcbf9"
            }
          ]
        }
      },
      "links": {
        "self": "/v1/routing/work-sessions/5dee34bb431fd301ab0fcc2a"
      }
    },
    {
      "id": "5dee34ba431fd301ab0fcc00",
      "type": "work_session",
      "attributes": {
        "routable": true,
        "statusType": "available",
        "workItemCount": 0,
        "pausedWorkItemCount": 0,
        "signedInAt": "2019-12-09T11:49:14.560Z",
        "capacity": [
          {
            "priority": 1,
            "limit": 10,
            "remaining": 10
          },
          {
            "priority": 10,
            "limit": 2,
            "remaining": 2
          }
        ],
        "capacityRemaining": 10,
        "totalCapacity": 10,
        "handledItemCount": 0,
        "handledConversationCount": 0,
        "totalAvailable": {
          "statusAt": "2019-12-09T11:49:14.560Z"
        },
        "totalTimeByStatus": {
          "5dee34ba431fd301ab0fcbf3": {
            "statusAt": "2019-12-09T11:49:14.560Z"
          }
        },
        "capacityStatus": "idle",
        "updatedAt": "2019-12-09T11:49:14.560Z",
        "modifiedAt": "2019-12-09T11:49:14.560Z",
        "createdAt": "2019-12-09T11:49:14.560Z",
        "rev": 1
      },
      "relationships": {
        "org": {
          "data": {
            "type": "org",
            "id": "55d7998f2d3f9f8800099aed"
          },
          "links": {
            "self": "/v1/orgs/55d7998f2d3f9f8800099aed"
          }
        },
        "user": {
          "data": {
            "type": "user",
            "id": "5dd7ff8f2d3f9f8800099aed"
          },
          "links": {
            "self": "/v1/users/5dd7ff8f2d3f9f8800099aed"
          }
        },
        "team": {
          "data": {
            "type": "team",
            "id": "55d79fff2d3f9f8800099aff"
          },
          "links": {
            "self": "/v1/teams/55d79fff2d3f9f8800099aff"
          }
        },
        "routingSettings": {
          "data": {
            "type": "team_routing_settings",
            "id": "5dee34ba431fd301ab0fcbfd"
          },
          "links": {
            "self": "/v1/routing/settings/5dee34ba431fd301ab0fcbfd"
          }
        },
        "status": {
          "data": {
            "type": "status",
            "id": "5dee34ba431fd301ab0fcbf3"
          },
          "links": {
            "self": "/v1/routing/statuses/5dee34ba431fd301ab0fcbf3"
          }
        },
        "modifiedBy": {
          "data": {
            "type": "user",
            "id": "5dd7ff8f2d3f9f8800099aed"
          },
          "links": {
            "self": "/v1/users/5dd7ff8f2d3f9f8800099aed"
          }
        },
        "queues": {
          "data": [
            {
              "type": "queue",
              "id": "5dee34ba431fd301ab0fcbf9"
            }
          ]
        },
        "lastRevision": {
          "data": {
            "type": "work_session_revision",
            "id": "5dee34ba431fd301ab0fcc01"
          }
        }
      },
      "links": {
        "self": "/v1/routing/work-sessions/5dee34ba431fd301ab0fcc00"
      }
    }
  ]
}