Skip to content
MoreVoiceDevelopers

Retrieve a queue's live state

GET
/queues/{id}/live
import MoreVoice from "@morevoice/sdk";


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


const queueLive = await mv.queues.retrieveLive("q_7Hk2Lm9Qp");
console.log(queueLive);

Who is waiting and for how long, which agents can take the calls, and today’s numbers. A snapshot: poll it, or follow queue.* events.

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 right now: waiting callers, the agents who can take them and today’s numbers.

object
agents
required

The queue’s signed-in members by status.

object
available
required
integer
>= -9007199254740991 <= 9007199254740991
away
required
integer
>= -9007199254740991 <= 9007199254740991
busy
required
integer
>= -9007199254740991 <= 9007199254740991
online
required

Members signed in, whatever their status.

integer
>= -9007199254740991 <= 9007199254740991
wrap_up
required
integer
>= -9007199254740991 <= 9007199254740991
as_of
required

An ISO-8601 timestamp in UTC.

string format: date-time
callbacks_offered
required

Callbacks ringing this queue’s agents right now.

integer
>= -9007199254740991 <= 9007199254740991
callers
required

Waiting callers, longest wait first.

Array<object>
object
call_id
required

A call ID (prefix call_).

string
/^call_[0-9A-Za-z]+$/
from
required

The caller’s number.

string | null
position
required

Place in line, from 1.

integer
>= -9007199254740991 <= 9007199254740991
state
required

ringing while an agent’s phone rings; connecting once one answered.

string
Allowed values: waiting ringing connecting
waited_seconds
required
integer
>= -9007199254740991 <= 9007199254740991
enabled
required
boolean
livemode
required

true in live mode, false in test mode.

boolean
longest_wait_seconds
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
members
required

The queue’s signed-in members.

Array<object>
object
call_id
required
Any of:

A call ID (prefix call_).

string
/^call_[0-9A-Za-z]+$/
name
required
string
since
required

An ISO-8601 timestamp in UTC.

string format: date-time
status
required
string
Allowed values: available busy wrap_up away offline
user_id
required

A user ID (prefix usr_).

string
/^usr_[0-9A-Za-z]+$/
object
required
string
Allowed value: queue_live
queue_id
required

A queue ID (prefix q_).

string
/^q_[0-9A-Za-z]+$/
today
required
Any of:
object
abandoned
required
integer
>= -9007199254740991 <= 9007199254740991
answered
required
integer
>= -9007199254740991 <= 9007199254740991
average_wait_seconds
required

Of answered calls.

number | null
callbacks
required
integer
>= -9007199254740991 <= 9007199254740991
calls
required
integer
>= -9007199254740991 <= 9007199254740991
max_wait_seconds
required
number | null
overflowed
required
integer
>= -9007199254740991 <= 9007199254740991
service_level
required

Share (0–1) of answered calls answered within 20 seconds.

number | null
voicemails
required
integer
>= -9007199254740991 <= 9007199254740991
waiting
required

Callers waiting for an agent right now.

integer
>= -9007199254740991 <= 9007199254740991
Example
{
  "agents": {
    "available": 2,
    "away": 1,
    "busy": 1,
    "online": 4,
    "wrap_up": 0
  },
  "as_of": "2026-11-03T09:14:22.000Z",
  "callbacks_offered": 0,
  "callers": [
    {
      "call_id": "call_5Fh7Jk9Lm1Np3Qr5St7Vx9",
      "from": "+972501234567",
      "position": 1,
      "state": "ringing",
      "waited_seconds": 42
    }
  ],
  "enabled": true,
  "livemode": true,
  "longest_wait_seconds": 42,
  "members": [
    {
      "call_id": null,
      "name": "Dana Levi",
      "since": "2026-11-03T09:10:00.000Z",
      "status": "available",
      "user_id": "usr_2Lm8Pq4Rt6Vx0Zb3Nd5Fh7"
    }
  ],
  "object": "queue_live",
  "queue_id": "q_4Gk2LmN9pQ4rS6tV8wX0yZ",
  "today": {
    "abandoned": 4,
    "answered": 31,
    "average_wait_seconds": 18,
    "callbacks": 1,
    "calls": 37,
    "max_wait_seconds": 96,
    "overflowed": 2,
    "service_level": 0.84,
    "voicemails": 1
  },
  "waiting": 1
}

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.