queues
Covers 5 API operations in the queues category.
| Method | Path | Description |
|---|---|---|
| GET | /v1/orgs/{orgSlug}/projects/{projectName}/queues | Queues: what is declared, how deep each is, what happened (runlot queue list) |
| GET | /v1/orgs/{orgSlug}/projects/{projectName}/queues/{queue}/runs | One queue's batch history |
| GET | /v1/orgs/{orgSlug}/projects/{projectName}/queues/{queue}/messages | The next messages, without leasing them (runlot queue peek) |
| DELETE | /v1/orgs/{orgSlug}/projects/{projectName}/queues/{queue}/messages | Empties the queue (runlot queue purge) |
| POST | /v1/orgs/{orgSlug}/projects/{projectName}/queues/{queue}/redrive | Moves a dead-letter queue's messages back (runlot queue redrive) |
GET /v1/orgs/{orgSlug}/projects/{projectName}/queues
Requires viewer or higher. Returns the declared queues, their current depth, and the recent delivery history in one call.
queues comes from the live deployment's manifest, one row per distinct name
across producers, consumers and dead-letter queues, in declaration order. Consumer
settings are reported with defaults already applied (maxBatchSize 10,
maxBatchTimeout 5 s, maxRetries 3).
The depth is read from the project's own database, where messages live in the
runlot_queue schema. A queue nothing has ever sent to reads as empty, because the
schema is installed on the first send. If the project's database cannot be reached,
depthError says so and depth is absent on every row; the declarations and the
history are still returned.
History is one row per batch, kept for keepDays (30 days free, 365 pro) and
then pruned. opsToday and opsCap are the project's daily operation count and
its plan's cap (free 10,000, pro 1,000,000; a send is one, a delivery is one).
operationId getProjectQueues
| Parameter | Location | Required | Type | Description |
|---|---|---|---|---|
limit | query | No | integer | How many history rows. Default 50, capped at 200. |
| Status code | Description | Response body |
|---|---|---|
| 200 | The declared queues with their depth, and the recent history | QueueOverview |
| 403 | — | — |
| 404 | — | — |
GET /v1/orgs/{orgSlug}/projects/{projectName}/queues/{queue}/runs
Requires viewer or higher. Newest first. The same batch rows getProjectQueues
returns, narrowed to a single queue.
operationId listQueueRuns
| Parameter | Location | Required | Type | Description |
|---|---|---|---|---|
limit | query | No | integer | Default 50, capped at 200. |
| Status code | Description | Response body |
|---|---|---|
| 200 | Batches of this queue | object |
| 400 | — | — |
| 403 | — | — |
| 404 | — | — |
GET /v1/orgs/{orgSlug}/projects/{projectName}/queues/{queue}/messages
Requires member. Reads the head of the queue in delivery order without reserving the
messages, so peeking never delays a delivery. Each row carries a preview — the body
clipped to 200 characters, or <n bytes> for a binary body — never the body itself.
A queue that has never received a message answers an empty list.
operationId peekQueue
| Parameter | Location | Required | Type | Description |
|---|---|---|---|---|
limit | query | No | integer | Default 10, capped at 100. |
| Status code | Description | Response body |
|---|---|---|
| 200 | The head of the queue | object |
| 400 | — | — |
| 403 | — | — |
| 404 | No such project, or the project has no database (not_found) | Error |
| 502 | console_unreachable — the project's database could not be reached | Error |
DELETE /v1/orgs/{orgSlug}/projects/{projectName}/queues/{queue}/messages
Requires member. Deletes every message in the queue — visible, delayed and in
flight — and answers with the count. It is irreversible and the server asks for no
confirmation: the CLI prompts unless you pass --yes, and the dashboard asks you
to type the queue's name back. The purge is audited with the count.
operationId purgeQueue
| Status code | Description | Response body |
|---|---|---|
| 200 | Purged | object |
| 400 | — | — |
| 403 | — | — |
| 404 | — | — |
POST /v1/orgs/{orgSlug}/projects/{projectName}/queues/{queue}/redrive
Requires member. {queue} is the dead-letter queue. Every message in it that is
not in flight moves to the destination with attempts reset to 0, so a redriven
message gets the full retry budget of the queue it returns to.
The destination is the consumer that names {queue} as its deadLetterQueue in the
live manifest. When two consumers share one dead-letter queue, or the queue is
nobody's dead-letter queue, to is required (400). Audited with the count.
operationId redriveQueue
Request body: application/json · object
| Status code | Description | Response body |
|---|---|---|
| 200 | Redriven | object |
| 400 | — | — |
| 403 | — | — |
| 404 | — | — |