# Get queue

> GET /v1/routing/queues/{id} · Queues and routing API

Source: https://developer.kustomer.com/api/queues-and-routing/get-queue

```http
GET https://{orgname}.api.kustomerapp.com/v1/routing/queues/{id}
Authorization: Bearer <API key>
```

## Authorization

Requires any one of these roles: `org.permission.queue.read`, `org.permission.routing.read`; or legacy `org.user.routing.read`. The API key or user must hold at least one of them. Legacy roles predate permission sets and still work.

Retrieves a queue by unique ID.

## About Queues

A queue is a named line of waiting work, such as "Billing" or "VIP Support", that routing uses to decide which agents can take a conversation and in what order. Each queue sets the priority and size of the work that enters it.

When a conversation needs an agent, routing places its [work item](https://developer.kustomer.com/api/queues-and-routing#work-items) in a queue and then offers it to an available agent on a team that works that queue. Admins manage queues in Kustomer's routing settings, and teams choose the queues they serve in their [team routing settings](https://developer.kustomer.com/api/queues-and-routing#team-routing-settings). A conversation gets a queue in one of three ways: a [queue rule](https://developer.kustomer.com/api/queues-and-routing#queue-rules) matches it, something sets the queue directly (a workflow, an agent transfer, or the `queue` on a work item), or nothing matches and it falls through to the default queue.

Every org has one system queue, returned with `system: true` and named `DEFAULT_QUEUE`, that catches conversations no rule matches. Queue rules can't target it, and the only field you can change on it is `restrictTransfersByUsers`: an update to the default queue must send that field and nothing else.

#### Priority and item size

These two fields are copied onto each work item every time it enters the queue, and they drive routing:

| Field | Range | Meaning |
| --- | --- | --- |
| `priority` | 1–100, default 1 | Lower numbers are more urgent. Routing hands out lower-numbered items first, and the oldest item first within the same priority. |
| `itemSize` | 1–100, default 1 | How much of an agent's capacity one item from this queue uses. A queue for complex cases might use 2 so agents hold fewer of them at once. |

Team routing settings can also cap how much capacity each priority may use, so an agent's slots aren't all filled by low-priority work.

#### Other fields

- `name` is required; `displayName` is what agents see, and `description` is free text.
- `key` is an optional stable identifier you choose, unique among the org's active queues. Queue rules can pick a queue by key with `queueKey`, and `GET /v1/routing/queues?key=` finds a queue without knowing its ID, which helps when the same setup exists in several orgs.
- `restrictTransfersByUsers`, when `true`, removes the queue from the list agents can transfer a conversation to. Queue rules can still send work there.

Queues deleted in the Kustomer app are kept as deleted records. Lists leave them out unless you pass `all=true`, which is useful when an older work item points at a queue that no longer appears.

#### Which endpoint to use

| To | Call |
| --- | --- |
| List queues | [`GET /v1/routing/queues`](https://developer.kustomer.com/api/queues-and-routing/get-queues), with `system=true` for the default queue or `key` to find one queue |
| Read one queue | [`GET /v1/routing/queues/{id}`](https://developer.kustomer.com/api/queues-and-routing/get-queue) |
| Create or change a queue | [`POST /v1/routing/queues`](https://developer.kustomer.com/api/queues-and-routing/create-queue) or [`PUT /v1/routing/queues/{id}`](https://developer.kustomer.com/api/queues-and-routing/update-queue-by-id) |
| See what's waiting in a queue | [`GET /v1/routing/queues/{id}/work-items`](https://developer.kustomer.com/api/queues-and-routing/get-work-items-in-a-queue) or the [next item](https://developer.kustomer.com/api/queues-and-routing/get-next-work-item-in-a-queue) |
| See who is staffing a queue | [`GET /v1/routing/queues/{id}/work-sessions`](https://developer.kustomer.com/api/queues-and-routing/get-work-sessions-by-queue-id) |
| Check current wait times | [`GET /v1/chat/queues/metrics/{ids}`](https://developer.kustomer.com/api/queues-and-routing/queue-metrics) |

`PUT` requires `name` and changes only the fields you send. Updating a deleted queue fails with `409 Conflict`, and so does creating a queue once the org has reached the number of queues its subscription allows.

Related: [Queue rules](https://developer.kustomer.com/api/queues-and-routing#queue-rules), [Work items](https://developer.kustomer.com/api/queues-and-routing#work-items), [Team routing settings](https://developer.kustomer.com/api/queues-and-routing#team-routing-settings), [Queue metrics](https://developer.kustomer.com/api/queues-and-routing#metrics)

### Recipes

#### 1. Create or update a queue by its key

Keep queues in step with a config file or another org, matching them by a `key` you choose instead of by ID.

**Step 1.** [`GET /v1/routing/queues`](https://developer.kustomer.com/api/queues-and-routing/get-queues.md). Look the queue up by `key`. Keys are unique among the org's active queues, so you get at most one result; deleted queues are left out.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/routing/queues?key=$QUEUE_KEY" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/routing/queues --query key=$QUEUE_KEY | jq -r '.data[0].id // empty'
```

**Step 2.** [`POST /v1/routing/queues`](https://developer.kustomer.com/api/queues-and-routing/create-queue.md). If nothing came back, create the queue with its `key`. Creating one past the number of queues your subscription allows fails with `409 Conflict`.

```bash title="cURL"
curl --request POST "https://api.kustomerapp.com/v1/routing/queues" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name": "Billing", "key": "billing", "displayName": "Billing", "priority": 2, "itemSize": 1}'
```

```bash title="kusty"
kusty api POST /v1/routing/queues \
  --data '{"name": "Billing", "key": "billing", "displayName": "Billing", "priority": 2, "itemSize": 1}'
```

**Step 3.** [`PUT /v1/routing/queues/{id}`](https://developer.kustomer.com/api/queues-and-routing/update-queue-by-id.md). If the queue exists, update it by ID. `name` is required on every `PUT`; other fields change only if you send them.

```bash title="cURL"
curl --request PUT "https://api.kustomerapp.com/v1/routing/queues/$QUEUE_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name": "Billing", "displayName": "Billing", "priority": 2, "itemSize": 1}'
```

```bash title="kusty"
kusty api PUT /v1/routing/queues/$QUEUE_ID \
  --data '{"name": "Billing", "displayName": "Billing", "priority": 2, "itemSize": 1}'
```

> Keys also let [queue rules](https://developer.kustomer.com/api/queues-and-routing#queue-rules) pick a queue with `queueKey`, so a rule set copied between orgs keeps working without ID changes.

#### 2. Show live queue health on a dashboard

For every queue, show the latest wait and how many agents can take work right now.

**Step 1.** [`GET /v1/routing/queues`](https://developer.kustomer.com/api/queues-and-routing/get-queues.md). List the org's queues. The default queue (`system: true`) is included; deleted queues aren't.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/routing/queues?pageSize=100" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/routing/queues --all | jq -r '[.data.id, .data.attributes.displayName] | @tsv' > queues.tsv
```

**Step 2.** [`GET /v1/chat/queues/metrics/{ids}`](https://developer.kustomer.com/api/queues-and-routing/queue-metrics.md). Ask for the latest wait times of up to 80 queues in one call, with the IDs comma-separated in the path. A `null` wait means the queue had no activity in the `rangeFrom` window.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/chat/queues/metrics/$QUEUE_IDS?rangeFrom=3600" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
QUEUE_IDS=$(cut -f1 queues.tsv | head -80 | paste -sd, -)
kusty api GET /v1/chat/queues/metrics/$QUEUE_IDS --query rangeFrom=3600 \
  | jq -r '.data[] | [.id, .attributes.name, .attributes.latestWaitTimeSeconds] | @tsv'
```

**Step 3.** [`GET /v1/routing/queues/{id}/work-sessions`](https://developer.kustomer.com/api/queues-and-routing/get-work-sessions-by-queue-id.md). For each queue, count the work sessions with `routable=true`: agents signed in to the queue, available and under capacity.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/routing/queues/$QUEUE_ID/work-sessions?routable=true&pageSize=100" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/routing/queues/$QUEUE_ID/work-sessions --query routable=true --all | wc -l
```

> The metrics endpoint is rate limited as a metrics endpoint, so refresh a dashboard every minute or so rather than on every view. For the number of items waiting, list the queue's work items with `status=queued`.

#### 3. Raise a queue's priority for a while

Push one queue's work ahead of the rest, for example during an outage, and put it back afterwards.

**Step 1.** [`GET /v1/routing/queues/{id}`](https://developer.kustomer.com/api/queues-and-routing/get-queue.md). Read the queue and note its `name` and current `priority`, so you can restore it later.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/routing/queues/$QUEUE_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/routing/queues/$QUEUE_ID --fields attributes.name,attributes.priority
```

**Step 2.** [`PUT /v1/routing/queues/{id}`](https://developer.kustomer.com/api/queues-and-routing/update-queue-by-id.md). Send the `name` and the new `priority`. Lower numbers are routed first, so `1` is the most urgent.

```bash title="cURL"
curl --request PUT "https://api.kustomerapp.com/v1/routing/queues/$QUEUE_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"name\": \"$QUEUE_NAME\", \"priority\": 1}"
```

```bash title="kusty"
kusty api PUT /v1/routing/queues/$QUEUE_ID --field name="$QUEUE_NAME" --field priority:=1
```

> A work item takes the queue's priority when it enters the queue, so the change applies to work that arrives after it. Items already waiting keep the priority they entered with. The default queue's priority can't be changed.

### Example object

A real record from [`GET /v1/routing/queues/{id}`](https://developer.kustomer.com/api/queues-and-routing/get-queue.md):

```json
{
  "id": "5de87b2969498a001ace7904",
  "type": "queue",
  "attributes": {
    "name": "VIP Queue",
    "displayName": "VIP Queue",
    "priority": 1,
    "itemSize": 1,
    "restrictTransfersByUsers": false,
    "system": false,
    "description": "Customer's with VIP Status",
    "updatedAt": "2019-12-05T03:36:09.341Z",
    "createdAt": "2019-12-05T03:36:09.341Z",
    "modifiedAt": "2019-12-05T03:36:09.341Z"
  },
  "relationships": {
    "org": {
      "data": {
        "type": "org",
        "id": "57504f64d76808100089eb44"
      },
      "links": {
        "self": "/v1/orgs/57504f64d76808100089eb44"
      }
    },
    "createdBy": {
      "data": {
        "type": "user",
        "id": "57504f644c80120f00f3c378"
      },
      "links": {
        "self": "/v1/users/57504f644c80120f00f3c378"
      }
    }
  },
  "links": {
    "self": "/v1/queues/5de87b2969498a001ace7904"
  }
}
```

Fields:

- `attributes.name` (string): The queue's name, required on create and on every `PUT`. Up to 256 characters.
- `attributes.displayName` (string): The name agents see. Falls back to `name` when not set.
- `attributes.priority` (integer): 1 to 100, default 1. Copied onto each work item as it enters the queue; lower numbers are routed first. Items already waiting keep the priority they entered with.
- `attributes.itemSize` (integer): 1 to 100, default 1. How much of an agent's capacity each work item from this queue uses.
- `attributes.restrictTransfersByUsers` (boolean): When `true`, agents can't pick this queue when transferring a conversation. Queue rules can still send work here.
- `attributes.system` (boolean): `true` only for the org's default queue, which catches conversations no rule matches. The only field you can change on it is `restrictTransfersByUsers`.
- `attributes.description` (string): Free text for admins, up to 1,024 characters.

### Relationships

- Referenced by **KObjects (custom objects)** via `relationships.queue`: For KObjects that are routed as work, such as tasks, the routing queue the KObject is in.
- Referenced by **Queue rules** via `relationships.queue`: The queue a queue rule sends matching conversations to. A rule can't point at the default queue, and rules that choose a queue by `queueKey` have no fixed queue.
- Referenced by **Queue metrics** via `relationships.queue`: The queue whose latest wait times these queue metrics report.
- Referenced by **Team routing settings** via `relationships.queues` (list): The queues a team works, from its team routing settings. Agents on the team are offered work items only from these queues, up to 10.
- Referenced by **Work items** via `relationships.queue`: The queue this work item waits in, or last waited in. The queue's `priority` and `itemSize` are copied onto the item each time it enters.
- Referenced by **Work sessions** via `relationships.queues` (list)

### Permissions

Fewest roles for a read-only integration: `org.permission.queue.read`. For every endpoint: `org.permission.queue.read`, `org.permission.queue.create`, `org.permission.queue.update`.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Queue ID |

## Responses

### 200

OK

- `data` (object, required)
  - `id` (string, required)
  - `type` (string, required)
  - `attributes` (object, required)
    - `name` (string, required)
    - `displayName` (string, required)
    - `priority` (integer, required)
    - `itemSize` (integer, required)
    - `restrictTransfersByUsers` (boolean, required)
    - `system` (boolean, required)
    - `description` (string, required)
    - `updatedAt` (string, required)
    - `createdAt` (string, required)
    - `modifiedAt` (string, required)
  - `relationships` (object, required)
    - `org` (object, required)
    - `createdBy` (object, required)
  - `links` (object, required)
    - `self` (string, required)

```json
{
  "data": {
    "id": "5de87b2969498a001ace7904",
    "type": "queue",
    "attributes": {
      "name": "VIP Queue",
      "displayName": "VIP Queue",
      "priority": 1,
      "itemSize": 1,
      "restrictTransfersByUsers": false,
      "system": false,
      "description": "Customer's with VIP Status",
      "updatedAt": "2019-12-05T03:36:09.341Z",
      "createdAt": "2019-12-05T03:36:09.341Z",
      "modifiedAt": "2019-12-05T03:36:09.341Z"
    },
    "relationships": {
      "org": {
        "data": {
          "type": "org",
          "id": "57504f64d76808100089eb44"
        },
        "links": {
          "self": "/v1/orgs/57504f64d76808100089eb44"
        }
      },
      "createdBy": {
        "data": {
          "type": "user",
          "id": "57504f644c80120f00f3c378"
        },
        "links": {
          "self": "/v1/users/57504f644c80120f00f3c378"
        }
      }
    },
    "links": {
      "self": "/v1/queues/5de87b2969498a001ace7904"
    }
  }
}
```

### 401

Unauthorized

### 403

Forbidden

### 404

Not Found

## Example request

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