API reference

Queues

Named lanes that set concurrency, priority, rate limits and retries for a kind of work.

A queue is a named lane for one kind of work. It decides how many jobs run at once, how fast they start and how failures are retried. Every job belongs to exactly one queue.

Queues are created from the dashboard or your halyard.yaml and are addressed by ID or by name, so /v3/queues/emails and /v3/queues/que_7Hn2Lp4Vc9 are the same queue.

Endpoints: 5
ID prefix: que_
Attributes: 11

The queue object

Every queue endpoint returns this object, or a list of them. Attributes marked null are always present in the response, so you can rely on the shape.

Attributes

idstring

Unique identifier, prefixed with que_.

objectstring

Always queue.

namestring

Unique name within your project, such as emails.

concurrencyinteger

Maximum jobs running at the same time across all workers.

priorityinteger

From -10 to 10. Workers that serve several queues pick higher ones first.

rate_limitobject | null

Caps how often jobs start, or null for no limit.

Show 2 child attributes

limitinteger

Jobs allowed to start per interval.

intervalduration

Window for the limit: 1s, 1m or 1h.

retry_policyobject

How failed jobs on this queue are retried. See Retries and backoff.

Show 4 child attributes

max_attemptsinteger

Attempts before a job is marked failed, including the first one. Between 1 and 25.

backoffenum

One of exponential, linear or fixed.

initial_delayduration

Delay before the first retry, such as 10s.

max_delayduration

Upper bound for the delay between attempts, such as 1h.

pausedboolean

true while the queue accepts jobs but doesn't hand them to workers.

countsobject

Live job counts, refreshed every few seconds.

Show 4 child attributes

queuedinteger

Waiting for a worker.

runninginteger

Currently on a worker.

scheduledinteger

Waiting for their run_at time.

failedinteger

Failed in the last 24 hours.

created_attimestamp

When the object was created, in ISO 8601 UTC.

livemodeboolean

true for objects created with a live key, false for the test sandbox.

The queue object

{  "id": "que_7Hn2Lp4Vc9",  "object": "queue",  "name": "emails",  "concurrency": 20,  "priority": 0,  "rate_limit": {    "limit": 100,    "interval": "1s"  },  "retry_policy": {    "max_attempts": 5,    "backoff": "exponential",    "initial_delay": "10s",    "max_delay": "1h"  },  "paused": false,  "counts": {    "queued": 42,    "running": 18,    "scheduled": 7,    "failed": 3  },  "created_at": "2026-03-11T10:04:52Z",  "livemode": false}

List queues

GET/v3/queues

Lists every queue in the project, sorted by name, with live job counts.

Query parameters

limitintegerdefault: 20

How many objects to return, between 1 and 100.

starting_afterstring

A cursor: the ID of the last object on the previous page. The next page starts right after it.

ending_beforestring

A cursor for paging backwards: the ID of the first object on the current page.

Returns

A list object with queue objects in data.

GET /v3/queues

curl -G https://api.halyard.example/v3/queues \  -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d" \  -d limit=2

import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const queues = await halyard.queues.list({  limit: 2,});

import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) queues = halyard.queues.list(limit=2)

Response200 OK

{  "object": "list",  "url": "/v3/queues",  "has_more": true,  "data": [    {      "id": "que_1Bz5Rt8Mw3",      "object": "queue",      "name": "billing",      "concurrency": 5,      "priority": 0,      "rate_limit": null,      "retry_policy": {        "max_attempts": 5,        "backoff": "exponential",        "initial_delay": "10s",        "max_delay": "1h"      },      "paused": false,      "counts": {        "queued": 3,        "running": 5,        "scheduled": 0,        "failed": 12      },      "created_at": "2026-03-11T10:04:52Z",      "livemode": false    },    {      "id": "que_7Hn2Lp4Vc9",      "object": "queue",      "name": "emails",      "concurrency": 20,      "priority": 0,      "rate_limit": {        "limit": 100,        "interval": "1s"      },      "retry_policy": {        "max_attempts": 5,        "backoff": "exponential",        "initial_delay": "10s",        "max_delay": "1h"      },      "paused": false,      "counts": {        "queued": 42,        "running": 18,        "scheduled": 7,        "failed": 3      },      "created_at": "2026-03-11T10:04:52Z",      "livemode": false    }  ]}

Retrieve a queue

GET/v3/queues/{id}

Fetches one queue with its settings and live counts.

Path parameters

idstringrequired

The queue's ID or name.

Returns

The queue object.

GET /v3/queues/{id}

curl https://api.halyard.example/v3/queues/emails \  -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d"

import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const queue = await halyard.queues.retrieve("emails");

import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) queue = halyard.queues.retrieve("emails")

Response200 OK

{  "id": "que_7Hn2Lp4Vc9",  "object": "queue",  "name": "emails",  "concurrency": 20,  "priority": 0,  "rate_limit": {    "limit": 100,    "interval": "1s"  },  "retry_policy": {    "max_attempts": 5,    "backoff": "exponential",    "initial_delay": "10s",    "max_delay": "1h"  },  "paused": false,  "counts": {    "queued": 42,    "running": 18,    "scheduled": 7,    "failed": 3  },  "created_at": "2026-03-11T10:04:52Z",  "livemode": false}

Update a queue

PATCH/v3/queues/{id}

Changes a queue's settings. Only the fields you send are updated. New limits apply to jobs that start after the change; running jobs are not interrupted.

Path parameters

idstringrequired

The queue's ID or name.

Body parameters

concurrencyinteger

Between 1 and 1000.

priorityinteger

From -10 to 10.

rate_limitobject | null

Send null to remove the limit.

Show 2 child attributes

limitintegerrequired

Jobs allowed to start per interval.

intervaldurationrequired

1s, 1m or 1h.

retry_policyobject

Fields you leave out keep their current value.

Show 4 child attributes

max_attemptsinteger

Attempts before a job is marked failed, including the first one. Between 1 and 25.

backoffenum

One of exponential, linear or fixed.

initial_delayduration

Delay before the first retry, such as 10s.

max_delayduration

Upper bound for the delay between attempts, such as 1h.

Returns

The updated queue object.

PATCH /v3/queues/{id}

curl -X PATCH https://api.halyard.example/v3/queues/emails \  -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d" \  -H "Content-Type: application/json" \  -d '{    "concurrency": 40,    "rate_limit": {      "limit": 200,      "interval": "1s"    }  }'

import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const queue = await halyard.queues.update("emails", {  concurrency: 40,  rate_limit: { limit: 200, interval: "1s" },});

import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) queue = halyard.queues.update(    "emails",    concurrency=40,    rate_limit={"limit": 200, "interval": "1s"},)

Response200 OK

{  "id": "que_7Hn2Lp4Vc9",  "object": "queue",  "name": "emails",  "concurrency": 40,  "priority": 0,  "rate_limit": {    "limit": 200,    "interval": "1s"  },  "retry_policy": {    "max_attempts": 5,    "backoff": "exponential",    "initial_delay": "10s",    "max_delay": "1h"  },  "paused": false,  "counts": {    "queued": 42,    "running": 18,    "scheduled": 7,    "failed": 3  },  "created_at": "2026-03-11T10:04:52Z",  "livemode": false}

Pause a queue

POST/v3/queues/{id}/pause

Stops handing jobs to workers. The queue still accepts new jobs, and jobs already running finish normally. Useful during a deploy or while a downstream service is down.

Path parameters

idstringrequired

The queue's ID or name.

Returns

The queue object with paused set to true.

POST /v3/queues/{id}/pause

curl -X POST https://api.halyard.example/v3/queues/emails/pause \  -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d"

import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const queue = await halyard.queues.pause("emails");

import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) queue = halyard.queues.pause("emails")

Response200 OK

{  "id": "que_7Hn2Lp4Vc9",  "object": "queue",  "name": "emails",  "concurrency": 20,  "priority": 0,  "rate_limit": {    "limit": 100,    "interval": "1s"  },  "retry_policy": {    "max_attempts": 5,    "backoff": "exponential",    "initial_delay": "10s",    "max_delay": "1h"  },  "paused": true,  "counts": {    "queued": 42,    "running": 18,    "scheduled": 7,    "failed": 3  },  "created_at": "2026-03-11T10:04:52Z",  "livemode": false}

Resume a queue

POST/v3/queues/{id}/resume

Starts handing jobs to workers again, oldest first and within the queue's rate limit.

Path parameters

idstringrequired

The queue's ID or name.

Returns

The queue object with paused set to false.

POST /v3/queues/{id}/resume

curl -X POST https://api.halyard.example/v3/queues/emails/resume \  -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d"

import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const queue = await halyard.queues.resume("emails");

import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) queue = halyard.queues.resume("emails")

Response200 OK

{  "id": "que_7Hn2Lp4Vc9",  "object": "queue",  "name": "emails",  "concurrency": 20,  "priority": 0,  "rate_limit": {    "limit": 100,    "interval": "1s"  },  "retry_policy": {    "max_attempts": 5,    "backoff": "exponential",    "initial_delay": "10s",    "max_delay": "1h"  },  "paused": false,  "counts": {    "queued": 42,    "running": 18,    "scheduled": 7,    "failed": 3  },  "created_at": "2026-03-11T10:04:52Z",  "livemode": false}

Overview

The queue object

List queues

Retrieve a queue

Update a queue

Pause a queue

Resume a queue