# Retrieve a queue

`GET https://api.morevoice.ai/v1/queues/{id}`

Returns the `Queue` object. Answers `404` with the code `resource_missing` when nothing has this ID in this organisation and mode.

Authenticate with a secret API key: `Authorization: Bearer $MOREVOICE_API_KEY`.

Operation ID: `queues_retrieve`.

## Parameters

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A queue ID (`q_…`). |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `MoreVoice-Version` | `string` | no | The API version to use for this request. Defaults to the version the API key is pinned to. |

## Responses

### 200 OK

OK Returns `Queue`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The queue's ID. |
| `object` | `"queue"` | — |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `name` | `string` | — |
| `enabled` | `boolean` | A disabled queue takes no calls: they overflow. |
| `strategy` | `"longest_idle" \| "round_robin"` | Which available agent rings first: the one idle longest, or in turn. |
| `member_user_ids` | `string[]` | Users who answer this queue's calls. |
| `member_team_ids` | `string[]` | Teams whose members answer this queue's calls. |
| `ring_timeout_seconds` | `integer` | How long an agent's phone rings before the next agent is tried. |
| `max_wait_seconds` | `integer` | How long a caller waits before the overflow action (0: no limit). |
| `wrap_up_seconds` | `integer` | After-call time before an agent gets the next call. |
| `away_on_missed` | `boolean` | An agent who misses a call is set to away. |
| `overflow` | `object` | What happens to callers who waited too long, or when nobody can answer. |
| `overflow.when_no_agents` | `boolean` | Overflow at once when no agent is signed in. |
| `overflow.action` | `"assistant" \| "voicemail" \| "busy" \| "agent" \| "queue" \| "number"` | — |
| `overflow.assistant_id` | `string \| null` | Action `assistant`: the AI assistant that answers. |
| `overflow.user_id` | `string \| null` | Action `agent`: the user who gets the call. |
| `overflow.queue_id` | `string \| null` | Action `queue`: the queue the call moves to. |
| `overflow.number` | `string` | Action `number`: the phone number the call is forwarded to. |
| `voicemail` | `object` | — |
| `voicemail.message` | `string` | Played before the beep (empty: the default). |
| `voicemail.max_seconds` | `integer` | — |
| `hold` | `object` | — |
| `hold.audio` | `"music" \| "ringback" \| "silence" \| "asset"` | What callers hear while they wait; `asset` plays `audio_asset_id` in a loop. |
| `hold.audio_asset_id` | `string \| null` | `aud_…` ID. |
| `hold.announcement` | `string` | Said to callers when they join the queue. |
| `hold.announce_position` | `boolean` | Tell callers their place in line. |
| `hold.position_interval_seconds` | `integer` | — |
| `wait_keys` | `object` | — |
| `wait_keys.voicemail` | `string` | Pressed while waiting: leave a voicemail (empty: off). |
| `wait_keys.callback` | `string` | Pressed while waiting: ask for a callback (empty: off). |
| `callbacks` | `object` | How callbacks requested in this queue are returned. |
| `callbacks.route` | `"agent_queue" \| "agent" \| "assistant"` | Who returns this queue's callbacks: its agents, one agent or an AI assistant. |
| `callbacks.agent_id` | `string \| null` | `usr_…` ID. |
| `callbacks.assistant_id` | `string \| null` | `asst_…` ID. |
| `callbacks.priority` | `integer` | 1 (low) to 10 (urgent). |
| `callbacks.voicemail_to_callback` | `boolean` | A voicemail left in this queue becomes a callback task too. |
| `voice_assistant_id` | `string \| null` | The assistant whose voice speaks the queue's announcements. |
| `copilot_profile_id` | `string \| null` | The copilot profile agents get on this queue's calls. |
| `created` | `string` | An ISO-8601 timestamp in UTC. |
| `updated` | `string` | An ISO-8601 timestamp in UTC. |

Example:

```json
{
  "away_on_missed": true,
  "callbacks": {
    "agent_id": null,
    "assistant_id": null,
    "priority": 5,
    "route": "agent_queue",
    "voicemail_to_callback": false
  },
  "copilot_profile_id": null,
  "created": "2026-11-03T09:14:22.000Z",
  "enabled": true,
  "hold": {
    "announce_position": false,
    "announcement": "",
    "audio": "music",
    "audio_asset_id": null,
    "position_interval_seconds": 45
  },
  "id": "q_4Gk2LmN9pQ4rS6tV8wX0yZ",
  "livemode": true,
  "max_wait_seconds": 120,
  "member_team_ids": [
    "team_7Hj2Kl4Mn6Pq8Rs0Tu2Vw"
  ],
  "member_user_ids": [
    "usr_2Lm8Pq4Rt6Vx0Zb3Nd5Fh7"
  ],
  "name": "Support",
  "object": "queue",
  "overflow": {
    "action": "assistant",
    "assistant_id": "asst_3cYbE6uYvGkH8w4ZK1rTqd",
    "number": "",
    "queue_id": null,
    "user_id": null,
    "when_no_agents": true
  },
  "ring_timeout_seconds": 20,
  "strategy": "longest_idle",
  "updated": "2026-11-03T09:14:22.000Z",
  "voice_assistant_id": null,
  "voicemail": {
    "max_seconds": 90,
    "message": ""
  },
  "wait_keys": {
    "callback": "",
    "voicemail": ""
  },
  "wrap_up_seconds": 15
}
```

### 400 Bad Request

The request is invalid: a parameter is missing, malformed or unknown, or the version header is unknown. Returns `ErrorEnvelope`.

### 401 Unauthorized

No valid API key was sent. Returns `ErrorEnvelope`.

### 403 Forbidden

The key may not do this (a missing scope, a plan limit, or a compliance block). Returns `ErrorEnvelope`.

### 404 Not Found

No object with this ID exists in this organisation and mode. Returns `ErrorEnvelope`.

### 429 Too Many Requests

Too many requests, or no call capacity right now. Retry after the Retry-After delay. Returns `ErrorEnvelope`.

### 500 Internal Server Error

Something went wrong on MoreVoice's side. Retry with the same Idempotency-Key. Returns `ErrorEnvelope`.

## Code samples

**TypeScript**

```ts
import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const queue = await mv.queues.retrieve("q_7Hk2Lm9Qp");
console.log(queue);
```

**Python**

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

queue = client.queues.retrieve("q_7Hk2Lm9Qp")
print(queue)
```

**cURL**

```sh
curl https://api.morevoice.ai/v1/queues/q_7Hk2Lm9Qp \
  -H "Authorization: Bearer $MOREVOICE_API_KEY"
```