Queues

A call queue holds incoming calls and distributes them to the agents logged into it. These endpoints report the live state (who is logged in, who is available, how many calls are waiting) and the historical statistics of the call queues of your account, and let you adjust the penalty of an agent in a queue. They are the natural companions of the agents endpoints, which act on the agents themselves, and of /queue_call, which places an outgoing call into a queue.

The account is normally implied by your API key. If your key gives access to several accounts, add an account parameter to select one.

List queues (live state)

GET https://api.ubity.com/queues

Parameter	Description
key	Your Ubity API key
monitor	(optional) '1' or 'true' to include today's monitoring statistics

Each entry of queues is keyed by the queue name and contains:

Field	Description
num_agents	Number of agents currently logged in the queue
available_agents	Extensions of the agents currently available
all_agents	Extensions of all the agents logged in the queue
waiting	The calls currently waiting in the queue

With monitor=1, each queue also contains queue_stats, inqueue, longest_wait, today_longest_wait and average_wait (durations are formatted as HH:MM:SS).

% curl -H "Accept: application/json;version=0" "https://api.ubity.com/queues?key=KKKK"

{
  "api_key": "KKKK",
  "code": 200,
  "diagnostic": "Success",
  "mode": "normal",
  "queues": {
    "myqueue-QQQQ": {
      "num_agents": 3,
      "available_agents": ["101", "103"],
      "all_agents": ["101", "102", "103"],
      "waiting": []
    }
  },
  "stamp": "2026-08-18 10:00",
  "time": "2026-08-18 10:00:12",
  "url": "https://api.ubity.com/queues?key=KKKK",
  "version": 0
}

List the agents of a queue

GET https://api.ubity.com/queue/<queue_name>/agents

(https://api.ubity.com/queue_agents/<queue_name> is an accepted alias)

Parameter	Description
key	Your Ubity API key

Returns one entry per agent of the queue, with (among others) the following fields:

Field	Description
agent	The agent's extension
fullname	The agent's full name
queue	The queue name
state	'available', 'oncall', 'paused', 'wrapuptime', ...
penalty	The agent's penalty in that queue (lower is called first)

Answers 404 if the queue does not exist in your account.

% curl -H "Accept: application/json;version=0" "https://api.ubity.com/queue/myqueue-QQQQ/agents?key=KKKK"

Set the penalty of an agent in a queue

The penalty orders the agents inside a queue: agents with a lower penalty are called first, and agents with a higher penalty only receive calls when the lower-penalty agents are busy or unavailable. This is a light-weight way to define primary and backup agents, or to temporarily push an agent to the back of a queue without logging them out.

PUT https://api.ubity.com/queue/<queue_name>/agent/<extension>

Parameter	Description
key	Your Ubity API key
penalty	'inc', 'dec', or a number >= 0

Returns the new penalty.

% curl -X PUT -H "Accept: application/json;version=0" "https://api.ubity.com/queue/myqueue-QQQQ/agent/101?key=KKKK" -d penalty=inc

{
  "api_key": "KKKK",
  "code": 200,
  "diagnostic": "Success",
  "mode": "normal",
  "penalty": 2,
  "stamp": "2026-08-18 10:05",
  "url": "https://api.ubity.com/queue/myqueue-QQQQ/agent/101?key=KKKK",
  "version": 0
}

Queue statistics

GET https://api.ubity.com/queue/<queue_name>/stats

GET https://api.ubity.com/queue/<queue_name>/stats/<start>

GET https://api.ubity.com/queue/<queue_name>/stats/<start>/<end>

Parameter	Description
key	Your Ubity API key
start	(optional, in URL) Unix timestamp (seconds); rounded down to start of the day
end	(optional, in URL) Unix timestamp (seconds); rounded up to end of the day
agent	(optional) restrict the statistics to one agent's extension

Use ALL as <queue_name> to get the statistics of every queue of the account.
Without start, the statistics cover the current day.
Without end, the statistics cover the single day of start.
The date range is limited (about 100 days); a larger range answers 400.

The reply contains, per queue: total_calls, answered_calls, abandoned_calls, average_duration, total_duration, average_waiting_duration, abandon_average_duration and abandon_percent, plus per-agent statistics and a grand total.

% curl -H "Accept: application/json;version=0" "https://api.ubity.com/queue/ALL/stats/1755230400/1755835200?key=KKKK"