List queues (user, pbx)

# Copy for LLM

Returns a paginated list of the calling PBX's call queues.

Auth. Either a user bearer token (abilities ['*']) or an Integrations API key carrying the queues scope. A key without queues responds 403.

Tenancy. The PBX is resolved from the token, never from the request. Only the caller's own queues are ever returned and no query parameter can widen that.

Shape. Read-only projection: the legacy voip_queue_id and the internal pool_id are not exposed, while mapping_id (the customer-visible correlation id) is. Queue membership is not part of this projection. Results are sorted by name ascending unless sort says otherwise. Linked Tempus statuses are opt-in through ?include=statuses; the statuses key is absent from the payload otherwise.

No free-text search. ?search= is not supported on this endpoint (the Queue model declares no searchable columns) and is ignored. It is available on /ivrs and /ivr-steps. Use filter[name] here instead.

Authorization Parameters Headers

HTTP: bearerAuth

User bearer token. Default authentication for customer-facing endpoints. Obtain a token by calling POST /login with your credentials, then send it on every subsequent request as Authorization: Bearer <token>. The token inherits the permissions and PBX scope of the authenticated user.

HTTP Authorization Scheme

bearer

Bearer format

Bearer <token>

HTTP: IntegrationApiKey

API key created on the Cockpit Integrations page (an "API key" integration). It is a bearer token owned by the customer's PBX and limited to the scopes selected when the key was created (e.g. phone-numbers, push-configuration).

Send it in the Authorization header:

Authorization: Bearer <api_key>

Manage keys (create / reveal / revoke) from Integrations → New integration → API key.

HTTP Authorization Scheme

bearer

page query · integer

Page number to fetch. Defaults to `1`.

per_page query · integer

Items per page. Values above the maximum, or below 1, fall back to the maximum, which is also the default.

sort query · string

Field to sort by, `-` prefixed for descending. Allowed: `id`, `name`, `mapping_id`, `call_flow_id`, `music_on_hold_id`, `ring_strategy`, `ring_busy_members`, `ring_twinnings`, `ring_duration`, `interval`, `wrap_up_time`, `exit_key`, `ring_empty`, `weight`, `enable_caller_position`, `caller_position_announce_frequency`, `caller_position_language`. Defaults to `name` ascending. Any other field responds 422.

filter[key] query · string

Narrow the list by one or more fields. Allowed keys: `id`, `name`, `mapping_id`, `call_flow_id`, `music_on_hold_id`, `ring_strategy`, `ring_busy_members`, `ring_twinnings`, `ring_duration`, `interval`, `wrap_up_time`, `exit_key`, `ring_empty`, `weight`, `enable_caller_position`, `caller_position_announce_frequency`, `caller_position_language`. Combine several with `filter[key1]=value1&filter[key2]=value2`. An unsupported key responds 422.

include query · string

Relation to embed. The only allowed value is `statuses`, which adds the linked Tempus statuses under `statuses`. Anything else responds 422.

enum: statuses

accept header · string

example: application/json

Responses

200 401 403 422 5XX

Response schema

Expand allCollapse all

dataarray<object>

Each item — A call queue as returned by the public v1 API (`GET /queues`, `GET /queues/{id}`). A queue distributes inbound calls across its member agents according to a ring strategy; callers wait while music-on-hold plays until a member becomes available. Timing fields: `ring_duration` (how long each agent is rung), `interval` (gap between ring attempts) and `wrap_up_time` (post-call cool-down before the agent is rung again). Queue membership (users, groups) is not part of this projection, and the legacy `voip_queue_id` and internal `pool_id` columns are deliberately not exposed. `mapping_id` IS exposed: it is the customer-visible correlation id.

id*string · uuid

Unique identifier of the queue.

read-only

example: 550e8400-e29b-41d4-a716-446655440000

pbx_id*string · uuid

Identifier of the Pbx (tenant) that owns this queue. Always the caller's own PBX: the endpoint never returns another tenant's queues.

read-only

example: 550e8400-e29b-41d4-a716-446655440001

mapping_idstring | null

External correlation id for this queue, used to line it up with the customer's own systems. Null when no mapping has been set.

example: 1042

call_flow_idstring | null · uuid

Identifier of the call flow followed when a waiting caller leaves the queue (for example by pressing `exit_key`). Null when none is attached.

example: 550e8400-e29b-41d4-a716-446655440005

music_on_hold_idstring | null · uuid

Identifier of the sound file (type `music`) played to waiting callers. Null when no music-on-hold is configured.

example: 550e8400-e29b-41d4-a716-446655440004

name*string

Human-readable name of the queue.

length: 0–128

example: Customer Support

ring_strategy*string | null

Order in which members are rung. `ring_all` rings everyone at once; `round_robin` cycles through members in turn; `least_recent` favours the member idle the longest; `fewest_calls` favours the member who has taken the fewest calls; `random` picks at random.

enum: fewest_calls least_recent round_robin ring_all random null

example: ring_all

ring_busy_members*boolean

Whether members already on a call are still rung for new queue calls.

example:

ring_twinnings*boolean

Whether a member's twinned devices ring alongside their desk phone.

example:

ring_duration*integer · int32

Seconds to ring a member before moving to the next; -1 means unlimited.

≥ -1

example: 20

interval*integer · int32

Seconds between successive ring attempts (0 means no wait).

≥ 0

example: 5

wrap_up_time*integer · int32

Seconds an agent stays unavailable after finishing a queue call (0 means no wait).

≥ 0

example: 30

exit_keystring | null

DTMF key a waiting caller can press to leave the queue and follow the attached call flow. Null when no exit key is configured.

enum: 0 1 2 3 4 5 6 7 8 9 * # null

example: 0

ring_empty*boolean

Whether callers may enter (and keep waiting) when no member is available.

example:

weight*integer · int32

Relative priority of this queue when an agent is a member of several queues: the higher the weight, the sooner this queue's callers are served.

example: 50

enable_caller_position*boolean

Whether waiting callers hear periodic announcements of their position in the queue.

example:

caller_position_announce_frequency*integer · int32

How often, in seconds, a waiting caller's position is announced.

≥ 0

example: 10

caller_position_language*string | null

Language used for the caller position announcement.

enum: en de fr null

example: en

created_at*string | null · date-time

Timestamp when the queue was created.

read-only

example: 2024-03-01T08:29:07.000000Z

updated_at*string | null · date-time

Timestamp when the queue was last updated.

read-only

example: 2024-03-01T08:29:07.000000Z

statusesarray<object>

The Tempus statuses linked to this queue (a member carrying one of these statuses is considered reachable for it). Present ONLY when the request carries `?include=statuses`; the key is absent from the payload otherwise. Curated projection: no pivot rows are returned.

id*string · uuid

Status identifier.

example: 550e8400-e29b-41d4-a716-446655440006

name*string

Human-readable status name.

example: Available

styleobject | null

Display style of the status badge in the cockpit.

icon_classstring

Font Awesome class of the status icon.

example: fas fa-car

bg_colorstring

Background color of the status badge, as a hex triplet.

example: #FFEEB2

availabilitystring | null

Presence bucket this status maps to.

enum: available unavailable busy meeting away null

example: available

do_not_disturbboolean

Whether a user on this status is treated as do-not-disturb.

example:

payableboolean

Whether time booked under this status counts as payable.

example: 1

mapping_idstring | null

External correlation id for the status. Null when unset.

example: 16

linksobject

firststring

The first page of the resource

example: http://localhost/api/v1/resources?page=1

laststring

The last page of the resource

example: http://localhost/api/v1/resources?page=1

prevnull | string

The previous page of the resource

nextnull | string

The next page of the resource

metaobject

current_pageinteger

The current page of the resource

≥ 1

example: 1

fromnull | integer

The first item of the resource

≥ 1

example: 1

last_pageinteger

The last page of the resource

≥ 1

example: 1

linksarray<object>

urlstring | null

The url of the resource (null for the boundary prev/next links)

example: http://localhost/api/v1/resources?page=1

labelstring

The label of the resource

example: first

activeboolean

The status of the resource

example: 1

pathstring

The path of the resource

example: http://localhost/api/v1/resources

per_pageinteger

The number of items per page of the resource

≥ 1

example: 15

tonull | integer

The last item of the resource

≥ 1

example: 1

totalinteger

The total number of items of the resource

≥ 0

example: 1

Authorization Token Missing. This error is returned when the authorization token is missing.

Response schema

errorstring

Error message

example: Authorization Token is missing

Forbidden. The bearer token authenticated successfully but does not carry the scope this endpoint requires. Re-create the Integrations API key with the missing scope selected (Integrations > New integration > API key).

Response schema

messagestring

Unprocessable Query. Two different problems share this status on the read endpoints: * a query parameter has the wrong TYPE (`page` / `per_page` not an integer, `filter` not an array, `sort` not a string). The body carries an `errors` map keyed by parameter name. * a `filter[...]` key, a `sort` field or an `include` relation that the endpoint does not allow was requested. The body carries a single `message` naming the allowed values. Nothing is returned and no partial result is produced: correct the query string and retry.

Response schema

Expand allCollapse all

messagestring

Present when an unsupported filter, sort or include was requested. The values it enumerates are the allow-list of the endpoint that returned it, so they differ per endpoint; the examples below show the `/ivrs` allow-list.

errorsobject

Present when a query parameter has the wrong type. Keyed by parameter name.

Free-form object

Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue.

Response schema

messagestring

exceptionstring

Only present in non-production environments.

filestring

Only present in non-production environments.

lineinteger

Only present in non-production environments.

get https://cockpit.voxbi.com/api/v1/queues

Base URL The production API server The staging API server The development API server

Request sample cURL JavaScript Python PHP

Copy

curl -X GET 'https://cockpit.voxbi.com/api/v1/queues' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Copy

const response = await fetch('https://cockpit.voxbi.com/api/v1/queues', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
});

const data = await response.json();
console.log(data);

Copy

import requests

response = requests.get('https://cockpit.voxbi.com/api/v1/queues',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'}
)
response.raise_for_status()
data = response.json()
print(data)

Copy

<?php
$context = stream_context_create([
    'http' => [
        'method'  => 'GET',
        'header'  => "Content-Type: application/json\r\nAuthorization: Bearer YOUR_TOKEN",
    ],
]);

$response = file_get_contents('https://cockpit.voxbi.com/api/v1/queues', false, $context);
$data = json_decode($response, true);
print_r($data);

Sample response Response headers

Expand all Collapse all Copy

{ … }

"data": [ … ],

{ … }

"id": "550e8400-e29b-41d4-a716-446655440000",

"pbx_id": "550e8400-e29b-41d4-a716-446655440001",

"mapping_id": "1042",

"call_flow_id": null,

"music_on_hold_id": "550e8400-e29b-41d4-a716-446655440004",

"name": "Customer Support",

"ring_strategy": "ring_all",

"ring_busy_members": false,

"ring_twinnings": false,

"ring_duration": 20,

"interval": 5,

"wrap_up_time": 30,

"exit_key": "0",

"ring_empty": false,

"weight": 50,

"enable_caller_position": false,

"caller_position_announce_frequency": 10,

"caller_position_language": "en",

"created_at": "2024-03-01T08:29:07.000000Z",

"updated_at": "2024-03-01T08:29:07.000000Z",

"statuses": [ … ]

{ … }

"id": "550e8400-e29b-41d4-a716-446655440006",

"name": "Available",

"style": { … },

"icon_class": "fas fa-car",

"bg_color": "#FFEEB2"

},

"availability": "available",

"do_not_disturb": false,

"payable": true,

"mapping_id": "16"

}

]

}

],

"links": { … },

"first": "https://cockpit.voxbi.com/api/v1/queues?page=1",

"last": "https://cockpit.voxbi.com/api/v1/queues?page=1",

"prev": null,

"next": null

},

"meta": { … }

"current_page": 1,

"from": 1,

"last_page": 1,

"path": "https://cockpit.voxbi.com/api/v1/queues",

"per_page": 100,

"to": 1,

"total": 1

}

}

Host string

example: cockpit.voxbi.com

Date string

example: Mon, 16 Oct 2023 14:08:48 GMT

Connection string

example: close

Cache-Control string

example: no-cache, private

Content-Type string

example: application/json

X-RateLimit-Limit integer

example: 60

X-RateLimit-Remaining integer

example: 59

Vary string

example: Origin

Sample response Response headers

Expand all Collapse all Copy

{ … }

"error": "Authorization Token is missing"

}

Cache-Control string

example: private, must-revalidate

Connection string

example: keep-alive

Content-Type string

example: application/json

Vary string

example: Origin

X-RateLimit-Limit integer

Max requests allowed in the current rate-limit window.

example: 60

X-RateLimit-Remaining integer

Requests remaining in the current rate-limit window.

example: 57

Sample response Response headers

Expand all Collapse all Copy

{ … }

"message": "Invalid ability provided."

}

Content-Type string

example: application/json

Sample response Response headers

Expand all Collapse all Copy

{ … }

"errors": { … }

"per_page": [ … ],

"The per page field must be an integer."

],

"sort": [ … ]

"The sort field must be a string."

]

}

}

Content-Type string

example: application/json

Sample response

Expand all Collapse all Copy

{ … }

"message": "Server Error"

}