Skip to content
MoreVoiceDevelopers

Retrieve a queue

GET
/queues/{id}
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);

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

Try it in the API playground with a test-mode key.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string
<= 200 characters /^q_[0-9A-Za-z]+$/

A queue ID (q_…).

Header Parameters

Section titled “Header Parameters”
MoreVoice-Version
string
/^\d{4}-\d{2}-\d{2}$/

The API version to use for this request. Defaults to the version the API key is pinned to.

Example
2026-11-01

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json

A queue of callers waiting for a human agent.

object
away_on_missed
required

An agent who misses a call is set to away.

boolean
callbacks
required

How callbacks requested in this queue are returned.

object
agent_id
required
Any of:

A user ID (prefix usr_).

string
/^usr_[0-9A-Za-z]+$/
assistant_id
required
Any of:

A assistant ID (prefix asst_).

string
/^asst_[0-9A-Za-z]+$/
priority
required

1 (low) to 10 (urgent).

integer
>= -9007199254740991 <= 9007199254740991
route
required

Who returns this queue’s callbacks: its agents, one agent or an AI assistant.

string
Allowed values: agent_queue agent assistant
voicemail_to_callback
required

A voicemail left in this queue becomes a callback task too.

boolean
copilot_profile_id
required
Any of:

A copilot profile ID (prefix cop_).

string
/^cop_[0-9A-Za-z]+$/
created
required

An ISO-8601 timestamp in UTC.

string format: date-time
enabled
required

A disabled queue takes no calls: they overflow.

boolean
hold
required
object
announce_position
required

Tell callers their place in line.

boolean
announcement
required

Said to callers when they join the queue.

string
audio
required

What callers hear while they wait; asset plays audio_asset_id in a loop.

string
Allowed values: music ringback silence asset
audio_asset_id
required
Any of:

A audio asset ID (prefix aud_).

string
/^aud_[0-9A-Za-z]+$/
position_interval_seconds
required
integer
>= -9007199254740991 <= 9007199254740991
id
required

The queue’s ID.

string
/^q_[0-9A-Za-z]+$/
livemode
required

true in live mode, false in test mode.

boolean
max_wait_seconds
required

How long a caller waits before the overflow action (0: no limit).

integer
>= -9007199254740991 <= 9007199254740991
member_team_ids
required

Teams whose members answer this queue’s calls.

Array<string>
member_user_ids
required

Users who answer this queue’s calls.

Array<string>
name
required
string
object
required
string
Allowed value: queue
overflow
required

What happens to callers who waited too long, or when nobody can answer.

object
action
required
string
Allowed values: assistant voicemail busy agent queue number
assistant_id
required
Any of:

A assistant ID (prefix asst_).

string
/^asst_[0-9A-Za-z]+$/
number
required

Action number: the phone number the call is forwarded to.

string
queue_id
required
Any of:

A queue ID (prefix q_).

string
/^q_[0-9A-Za-z]+$/
user_id
required
Any of:

A user ID (prefix usr_).

string
/^usr_[0-9A-Za-z]+$/
when_no_agents
required

Overflow at once when no agent is signed in.

boolean
ring_timeout_seconds
required

How long an agent’s phone rings before the next agent is tried.

integer
>= -9007199254740991 <= 9007199254740991
strategy
required

Which available agent rings first: the one idle longest, or in turn.

string
Allowed values: longest_idle round_robin
updated
required

An ISO-8601 timestamp in UTC.

string format: date-time
voice_assistant_id
required
Any of:

A assistant ID (prefix asst_).

string
/^asst_[0-9A-Za-z]+$/
voicemail
required
object
max_seconds
required
integer
>= -9007199254740991 <= 9007199254740991
message
required

Played before the beep (empty: the default).

string
wait_keys
required
object
callback
required

Pressed while waiting: ask for a callback (empty: off).

string
voicemail
required

Pressed while waiting: leave a voicemail (empty: off).

string
wrap_up_seconds
required

After-call time before an agent gets the next call.

integer
>= -9007199254740991 <= 9007199254740991
Example
{
  "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

Section titled “400”

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

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "parameter_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#parameter-missing",
    "message": "Missing required parameter: to.",
    "param": "to",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "invalid_request_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

401

Section titled “401”

No valid API key was sent.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "invalid_api_key",
    "doc_url": "https://docs.morevoice.ai/api/errors#invalid-api-key",
    "message": "Invalid API key.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "authentication_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

403

Section titled “403”

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

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "missing_scope",
    "doc_url": "https://docs.morevoice.ai/api/errors#missing-scope",
    "message": "This API key lacks the calls:write scope.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "permission_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

404

Section titled “404”

No object with this ID exists in this organisation and mode.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "resource_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#resource-missing",
    "message": "No such object: 'call_4Gk2'.",
    "param": "id",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "not_found"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

429

Section titled “429”

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

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "rate_limited",
    "doc_url": "https://docs.morevoice.ai/api/errors#rate-limited",
    "message": "Too many requests. Retry after 1 second.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "rate_limit_error"
  }
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before retrying.

X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

500

Section titled “500”

Something went wrong on MoreVoice’s side. Retry with the same Idempotency-Key.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "internal_error",
    "doc_url": "https://docs.morevoice.ai/api/errors#internal-error",
    "message": "Something went wrong on MoreVoice's side.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "api_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.