Skip to content

Get the live call queue

GET
/v1/studios/{studio}/queue
curl --request GET \
--url https://api.caller9.app/v1/studios/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/queue \
--header 'Authorization: Bearer <token>'

Returns every live (not yet ended) call in the studio, split into the main queue and the hotline (priority) lane, each ordered by queue position. Includes calls that are queued (ringing, unanswered) as well as calls already on hold, on-air, in a browser, or screening. Also returns the studio’s busy/screen-all flags and the current Contest Mode state.

studio
required
string format: uuid

Studio ID (UUID).

Live queue snapshot.

Media typeapplication/json
object
queue
required

Main-queue live calls, in queue order.

Array<object>

A live call as shown in the studio queue. Additional internal fields may be present and should be ignored.

object
guid
required

Call id (use with /v1/calls/{call}/…).

string
direction
required
string
Allowed values: inbound outbound
number
required

External party in E.164 (caller for inbound, callee for outbound).

string
caller
required

Display name (contact name, or the number).

string
status
required
string
Allowed values: queued screening hold browser on-air
call_type
required
string
Allowed values: primary hotline
conference_name

Where the caller currently is: hold, hybrid:N (on-air line N), browser:<userId>, or null while queued.

string | null
queue_order
required

Sort key for queue position (ascending). Values are not contiguous.

integer
called_number

The organization number that was dialed (inbound only).

string | null
called_name

Label of the dialed number.

string | null
queued_at
string | null format: date-time
initiated_at
required
string format: date-time
answered_at
string | null format: date-time
ended_at
string | null format: date-time
ring_deadline

When the studio’s ring-timeout action fires for this queued call.

string | null format: date-time
screening_started_at
string | null format: date-time
screening_ended_at
string | null format: date-time
location
string | null
mood
string | null
notes
string | null
tags

JSON-encoded array of strings (e.g. "[\"vip\"]"), not a native array.

string | null
favourite
integer
Allowed values: 0 1
point

Call topic / talking points (this call only).

string | null
codec

Audio codec negotiated with the caller; null until answered.

string | null
key
additional properties
any
hotline
required

Hotline (priority lane) live calls.

Array<object>

A live call as shown in the studio queue. Additional internal fields may be present and should be ignored.

object
guid
required

Call id (use with /v1/calls/{call}/…).

string
direction
required
string
Allowed values: inbound outbound
number
required

External party in E.164 (caller for inbound, callee for outbound).

string
caller
required

Display name (contact name, or the number).

string
status
required
string
Allowed values: queued screening hold browser on-air
call_type
required
string
Allowed values: primary hotline
conference_name

Where the caller currently is: hold, hybrid:N (on-air line N), browser:<userId>, or null while queued.

string | null
queue_order
required

Sort key for queue position (ascending). Values are not contiguous.

integer
called_number

The organization number that was dialed (inbound only).

string | null
called_name

Label of the dialed number.

string | null
queued_at
string | null format: date-time
initiated_at
required
string format: date-time
answered_at
string | null format: date-time
ended_at
string | null format: date-time
ring_deadline

When the studio’s ring-timeout action fires for this queued call.

string | null format: date-time
screening_started_at
string | null format: date-time
screening_ended_at
string | null format: date-time
location
string | null
mood
string | null
notes
string | null
tags

JSON-encoded array of strings (e.g. "[\"vip\"]"), not a native array.

string | null
favourite
integer
Allowed values: 0 1
point

Call topic / talking points (this call only).

string | null
codec

Audio codec negotiated with the caller; null until answered.

string | null
key
additional properties
any
config

Omitted if the studio configuration could not be loaded.

object
busy_all

1 when the studio is set to busy (do-not-disturb).

integer
Allowed values: 0 1
screen_all

1 when Screen All Calls is on.

integer
Allowed values: 0 1
contest
required
object
armed
required
boolean
phase

Current contest phase (present only when armed).

string
count

Callers counted so far (present only when armed).

integer
target

Winning caller number, e.g. 9 for “be caller 9”.

integer
backups

Number of backup winners after the target.

integer

Example

{
"queue": [
{
"direction": "inbound",
"status": "queued",
"call_type": "primary",
"favourite": 0
}
],
"hotline": [
{
"direction": "inbound",
"status": "queued",
"call_type": "primary",
"favourite": 0
}
],
"config": {
"busy_all": 0,
"screen_all": 0
}
}

Missing, invalid, expired or revoked API key.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

The key isn’t allowed to do this (e.g. a read-only key making a change).

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Not found, or belongs to another organization.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Too many requests for this API key. Retry after Retry-After seconds.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}
Retry-After
integer

Seconds until the rate-limit window resets.