Add Queue Management API endpoints and SDK documentation (#3087)
Closes #<issue> ## ✅ Checklist - [ ] I have followed every step in the [contributing guide](https://github.com/triggerdotdev/trigger.dev/blob/main/CONTRIBUTING.md) - [ ] The PR title follows the convention. - [ ] I ran and tested the code works --- ## Testing N/A - Documentation and OpenAPI schema updates only. --- ## Changelog Added comprehensive Queue Management API support: **OpenAPI Endpoints:** - `GET /api/v1/queues` - List all queues with pagination support - `GET /api/v1/queues/{queueParam}` - Retrieve a specific queue by ID, task ID, or custom queue name - `POST /api/v1/queues/{queueParam}/pause` - Pause or resume a queue - `POST /api/v1/queues/{queueParam}/concurrency/override` - Override queue concurrency limits - `POST /api/v1/queues/{queueParam}/concurrency/reset` - Reset concurrency limits to base values **Schema Definitions:** - `QueueObject` - Complete queue representation with concurrency details - `ListQueuesResult` - Paginated queue listing response **Documentation:** - Updated `queue-concurrency.mdx` with SDK usage examples for queue management - Added 5 new management API documentation pages for each endpoint - Updated `docs.json` navigation structure with new "Queues API" section All endpoints support flexible queue identification (by ID, task ID, or custom queue name) and include TypeScript code samples. --- ## Screenshots N/A 💯 https://claude.ai/code/session_01LyrXwxHCbejvi34fykifPP Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Matt Aitken
@@ -255,6 +255,16 @@
|
||||
"management/runs/update-metadata"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Queues API",
|
||||
"pages": [
|
||||
"management/queues/list",
|
||||
"management/queues/retrieve",
|
||||
"management/queues/pause",
|
||||
"management/queues/concurrency-override",
|
||||
"management/queues/concurrency-reset"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Schedules API",
|
||||
"pages": [
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
---
|
||||
title: "Override Concurrency Limit"
|
||||
openapi: "v3-openapi POST /api/v1/queues/{queueParam}/concurrency/override"
|
||||
---
|
||||
@@ -0,0 +1,4 @@
|
||||
---
|
||||
title: "Reset Concurrency Limit"
|
||||
openapi: "v3-openapi POST /api/v1/queues/{queueParam}/concurrency/reset"
|
||||
---
|
||||
@@ -0,0 +1,4 @@
|
||||
---
|
||||
title: "List Queues"
|
||||
openapi: "v3-openapi GET /api/v1/queues"
|
||||
---
|
||||
@@ -0,0 +1,4 @@
|
||||
---
|
||||
title: "Pause or Resume Queue"
|
||||
openapi: "v3-openapi POST /api/v1/queues/{queueParam}/pause"
|
||||
---
|
||||
@@ -0,0 +1,4 @@
|
||||
---
|
||||
title: "Retrieve Queue"
|
||||
openapi: "v3-openapi GET /api/v1/queues/{queueParam}"
|
||||
---
|
||||
@@ -226,3 +226,129 @@ export const subtask = task({
|
||||
```
|
||||
|
||||
When the parent task reaches the `triggerAndWait` call, it checkpoints and transitions to the `WAITING` state, releasing its concurrency slot back to both its queue and the environment. Once the subtask completes, the parent task will resume and re-acquire a concurrency slot.
|
||||
|
||||
## Managing queues with the SDK
|
||||
|
||||
The SDK provides a `queues` namespace that allows you to manage queues programmatically. You can list, retrieve, pause, resume, and modify concurrency limits for queues.
|
||||
|
||||
<Note>
|
||||
Import from `@trigger.dev/sdk`:
|
||||
```ts
|
||||
import { queues } from "@trigger.dev/sdk";
|
||||
```
|
||||
</Note>
|
||||
|
||||
### Listing queues
|
||||
|
||||
You can list all queues in your environment with pagination support:
|
||||
|
||||
```ts
|
||||
import { queues } from "@trigger.dev/sdk";
|
||||
|
||||
// List all queues (returns paginated results)
|
||||
const allQueues = await queues.list();
|
||||
|
||||
// With pagination options
|
||||
const pagedQueues = await queues.list({
|
||||
page: 1,
|
||||
perPage: 20,
|
||||
});
|
||||
```
|
||||
|
||||
### Retrieving a queue
|
||||
|
||||
You can retrieve a specific queue by its ID, or by its type and name:
|
||||
|
||||
```ts
|
||||
import { queues } from "@trigger.dev/sdk";
|
||||
|
||||
// Using queue ID (starts with "queue_")
|
||||
const queueById = await queues.retrieve("queue_1234");
|
||||
|
||||
// Using type and name for a task's default queue
|
||||
const taskQueue = await queues.retrieve({
|
||||
type: "task",
|
||||
name: "my-task-id",
|
||||
});
|
||||
|
||||
// Using type and name for a custom queue
|
||||
const customQueue = await queues.retrieve({
|
||||
type: "custom",
|
||||
name: "my-custom-queue",
|
||||
});
|
||||
```
|
||||
|
||||
The queue object contains useful information about the queue state:
|
||||
|
||||
```ts
|
||||
{
|
||||
id: "queue_1234", // Queue ID
|
||||
name: "my-task-id", // Queue name
|
||||
type: "task", // "task" or "custom"
|
||||
running: 5, // Currently executing runs
|
||||
queued: 10, // Runs waiting to execute
|
||||
paused: false, // Whether the queue is paused
|
||||
concurrencyLimit: 10, // Current concurrency limit
|
||||
concurrency: {
|
||||
current: 10, // Effective limit
|
||||
base: 10, // Default limit from code
|
||||
override: null, // Override value (if set)
|
||||
overriddenAt: null, // When override was applied
|
||||
overriddenBy: null, // Who applied the override
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Pausing and resuming queues
|
||||
|
||||
You can pause a queue to prevent new runs from starting. Runs that are currently executing will continue to completion.
|
||||
|
||||
```ts
|
||||
import { queues } from "@trigger.dev/sdk";
|
||||
|
||||
// Pause a queue using its ID
|
||||
await queues.pause("queue_1234");
|
||||
|
||||
// Or using type and name
|
||||
await queues.pause({ type: "task", name: "my-task-id" });
|
||||
await queues.pause({ type: "custom", name: "my-custom-queue" });
|
||||
```
|
||||
|
||||
To resume a paused queue and allow new runs to start:
|
||||
|
||||
```ts
|
||||
import { queues } from "@trigger.dev/sdk";
|
||||
|
||||
// Resume a queue using its ID
|
||||
await queues.resume("queue_1234");
|
||||
|
||||
// Or using type and name
|
||||
await queues.resume({ type: "task", name: "my-task-id" });
|
||||
await queues.resume({ type: "custom", name: "my-custom-queue" });
|
||||
```
|
||||
|
||||
### Overriding concurrency limits
|
||||
|
||||
You can temporarily override a queue's concurrency limit. This is useful for scaling up or down based on demand:
|
||||
|
||||
```ts
|
||||
import { queues } from "@trigger.dev/sdk";
|
||||
|
||||
// Set concurrency limit to 5
|
||||
await queues.overrideConcurrencyLimit("queue_1234", 5);
|
||||
|
||||
// Or using type and name
|
||||
await queues.overrideConcurrencyLimit({ type: "task", name: "my-task-id" }, 20);
|
||||
```
|
||||
|
||||
To reset the concurrency limit back to the base value defined in your code:
|
||||
|
||||
```ts
|
||||
import { queues } from "@trigger.dev/sdk";
|
||||
|
||||
// Reset concurrency limit to the base value
|
||||
await queues.resetConcurrencyLimit("queue_1234");
|
||||
|
||||
// Or using type and name
|
||||
await queues.resetConcurrencyLimit({ type: "task", name: "my-task-id" });
|
||||
```
|
||||
|
||||
@@ -1618,6 +1618,301 @@ paths:
|
||||
]
|
||||
}'
|
||||
|
||||
"/api/v1/queues":
|
||||
get:
|
||||
operationId: list_queues_v1
|
||||
summary: List all queues
|
||||
description: List all queues in your environment with pagination support.
|
||||
parameters:
|
||||
- in: query
|
||||
name: page
|
||||
schema:
|
||||
type: integer
|
||||
required: false
|
||||
description: Page number of the queue listing (1-based)
|
||||
- in: query
|
||||
name: perPage
|
||||
schema:
|
||||
type: integer
|
||||
required: false
|
||||
description: Number of queues per page
|
||||
responses:
|
||||
"200":
|
||||
description: Successful request
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
"$ref": "#/components/schemas/ListQueuesResult"
|
||||
"401":
|
||||
description: Unauthorized request
|
||||
tags:
|
||||
- queues
|
||||
security:
|
||||
- secretKey: []
|
||||
x-codeSamples:
|
||||
- lang: typescript
|
||||
source: |-
|
||||
import { queues } from "@trigger.dev/sdk";
|
||||
|
||||
// List all queues
|
||||
const allQueues = await queues.list();
|
||||
|
||||
// With pagination
|
||||
const pagedQueues = await queues.list({
|
||||
page: 1,
|
||||
perPage: 20,
|
||||
});
|
||||
|
||||
"/api/v1/queues/{queueParam}":
|
||||
get:
|
||||
operationId: retrieve_queue_v1
|
||||
summary: Retrieve a queue
|
||||
description: Get a queue by its ID, or by type and name.
|
||||
parameters:
|
||||
- in: path
|
||||
name: queueParam
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
description: The queue ID (e.g., `queue_1234`), or the name of the queue when using the `type` query parameter.
|
||||
example: queue_1234
|
||||
- in: query
|
||||
name: type
|
||||
schema:
|
||||
type: string
|
||||
enum: [id, task, custom]
|
||||
default: id
|
||||
required: false
|
||||
description: |
|
||||
How to interpret the `queueParam` path parameter:
|
||||
- `id`: Treat as a queue ID (default)
|
||||
- `task`: Treat as a task ID to get the task's default queue
|
||||
- `custom`: Treat as a custom queue name
|
||||
responses:
|
||||
"200":
|
||||
description: Successful request
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
"$ref": "#/components/schemas/QueueObject"
|
||||
"401":
|
||||
description: Unauthorized request
|
||||
"404":
|
||||
description: Queue not found
|
||||
tags:
|
||||
- queues
|
||||
security:
|
||||
- secretKey: []
|
||||
x-codeSamples:
|
||||
- lang: typescript
|
||||
source: |-
|
||||
import { queues } from "@trigger.dev/sdk";
|
||||
|
||||
// Using queue ID
|
||||
const queue = await queues.retrieve("queue_1234");
|
||||
|
||||
// Using type and name for a task queue
|
||||
const taskQueue = await queues.retrieve({
|
||||
type: "task",
|
||||
name: "my-task-id",
|
||||
});
|
||||
|
||||
// Using type and name for a custom queue
|
||||
const customQueue = await queues.retrieve({
|
||||
type: "custom",
|
||||
name: "my-custom-queue",
|
||||
});
|
||||
|
||||
"/api/v1/queues/{queueParam}/pause":
|
||||
post:
|
||||
operationId: pause_queue_v1
|
||||
summary: Pause or resume a queue
|
||||
description: Pause a queue to prevent new runs from starting, or resume a paused queue. Runs that are currently executing will continue to completion.
|
||||
parameters:
|
||||
- in: path
|
||||
name: queueParam
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
description: The queue ID (e.g., `queue_1234`), or the name of the queue when using the `type` body parameter.
|
||||
example: queue_1234
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: ["action"]
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
enum: [id, task, custom]
|
||||
default: id
|
||||
description: |
|
||||
How to interpret the `queueParam` path parameter:
|
||||
- `id`: Treat as a queue ID (default)
|
||||
- `task`: Treat as a task ID to get the task's default queue
|
||||
- `custom`: Treat as a custom queue name
|
||||
action:
|
||||
type: string
|
||||
enum: [pause, resume]
|
||||
description: Whether to pause or resume the queue
|
||||
responses:
|
||||
"200":
|
||||
description: Queue paused or resumed successfully
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
"$ref": "#/components/schemas/QueueObject"
|
||||
"400":
|
||||
description: Invalid request parameters
|
||||
"401":
|
||||
description: Unauthorized request
|
||||
"404":
|
||||
description: Queue not found
|
||||
tags:
|
||||
- queues
|
||||
security:
|
||||
- secretKey: []
|
||||
x-codeSamples:
|
||||
- lang: typescript
|
||||
source: |-
|
||||
import { queues } from "@trigger.dev/sdk";
|
||||
|
||||
// Pause a queue
|
||||
await queues.pause("queue_1234");
|
||||
await queues.pause({ type: "task", name: "my-task-id" });
|
||||
|
||||
// Resume a queue
|
||||
await queues.resume("queue_1234");
|
||||
await queues.resume({ type: "task", name: "my-task-id" });
|
||||
|
||||
"/api/v1/queues/{queueParam}/concurrency/override":
|
||||
post:
|
||||
operationId: override_queue_concurrency_v1
|
||||
summary: Override queue concurrency limit
|
||||
description: Override the concurrency limit of a queue. This is useful for temporarily scaling up or down based on demand.
|
||||
parameters:
|
||||
- in: path
|
||||
name: queueParam
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
description: The queue ID (e.g., `queue_1234`), or the name of the queue when using the `type` body parameter.
|
||||
example: queue_1234
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: ["concurrencyLimit"]
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
enum: [id, task, custom]
|
||||
default: id
|
||||
description: |
|
||||
How to interpret the `queueParam` path parameter:
|
||||
- `id`: Treat as a queue ID (default)
|
||||
- `task`: Treat as a task ID to get the task's default queue
|
||||
- `custom`: Treat as a custom queue name
|
||||
concurrencyLimit:
|
||||
type: integer
|
||||
minimum: 0
|
||||
maximum: 100000
|
||||
description: The new concurrency limit to set for the queue
|
||||
responses:
|
||||
"200":
|
||||
description: Concurrency limit overridden successfully
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
"$ref": "#/components/schemas/QueueObject"
|
||||
"400":
|
||||
description: Invalid request parameters
|
||||
"401":
|
||||
description: Unauthorized request
|
||||
"404":
|
||||
description: Queue not found
|
||||
tags:
|
||||
- queues
|
||||
security:
|
||||
- secretKey: []
|
||||
x-codeSamples:
|
||||
- lang: typescript
|
||||
source: |-
|
||||
import { queues } from "@trigger.dev/sdk";
|
||||
|
||||
// Override concurrency limit to 5
|
||||
await queues.overrideConcurrencyLimit("queue_1234", 5);
|
||||
|
||||
// Using type and name
|
||||
await queues.overrideConcurrencyLimit(
|
||||
{ type: "task", name: "my-task-id" },
|
||||
20
|
||||
);
|
||||
|
||||
"/api/v1/queues/{queueParam}/concurrency/reset":
|
||||
post:
|
||||
operationId: reset_queue_concurrency_v1
|
||||
summary: Reset queue concurrency limit
|
||||
description: Reset the concurrency limit of a queue back to its base value defined in code.
|
||||
parameters:
|
||||
- in: path
|
||||
name: queueParam
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
description: The queue ID (e.g., `queue_1234`), or the name of the queue when using the `type` body parameter.
|
||||
example: queue_1234
|
||||
requestBody:
|
||||
required: false
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
enum: [id, task, custom]
|
||||
default: id
|
||||
description: |
|
||||
How to interpret the `queueParam` path parameter:
|
||||
- `id`: Treat as a queue ID (default)
|
||||
- `task`: Treat as a task ID to get the task's default queue
|
||||
- `custom`: Treat as a custom queue name
|
||||
responses:
|
||||
"200":
|
||||
description: Concurrency limit reset successfully
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
"$ref": "#/components/schemas/QueueObject"
|
||||
"400":
|
||||
description: Queue is not overridden or invalid request parameters
|
||||
"401":
|
||||
description: Unauthorized request
|
||||
"404":
|
||||
description: Queue not found
|
||||
tags:
|
||||
- queues
|
||||
security:
|
||||
- secretKey: []
|
||||
x-codeSamples:
|
||||
- lang: typescript
|
||||
source: |-
|
||||
import { queues } from "@trigger.dev/sdk";
|
||||
|
||||
// Reset concurrency limit to the base value
|
||||
await queues.resetConcurrencyLimit("queue_1234");
|
||||
|
||||
// Using type and name
|
||||
await queues.resetConcurrencyLimit({
|
||||
type: "task",
|
||||
name: "my-task-id",
|
||||
});
|
||||
|
||||
components:
|
||||
parameters:
|
||||
taskIdentifier:
|
||||
@@ -1763,6 +2058,97 @@ components:
|
||||
minimum: 0
|
||||
maximum: 1000
|
||||
description: An optional property that specifies the maximum number of concurrent run executions. If this property is omitted, the task can potentially use up the full concurrency of an environment.
|
||||
QueueObject:
|
||||
type: object
|
||||
required: ["id", "name", "type", "running", "queued", "paused"]
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: The queue ID, e.g., `queue_1234`
|
||||
example: queue_1234
|
||||
name:
|
||||
type: string
|
||||
description: The queue name. For task queues, this is the task ID. For custom queues, this is the name you specified.
|
||||
example: my-task-id
|
||||
type:
|
||||
type: string
|
||||
enum: [task, custom]
|
||||
description: |
|
||||
The type of queue:
|
||||
- `task`: Created automatically for each task
|
||||
- `custom`: Created explicitly in your code using `queue()`
|
||||
example: task
|
||||
running:
|
||||
type: integer
|
||||
description: The number of runs currently executing
|
||||
example: 5
|
||||
queued:
|
||||
type: integer
|
||||
description: The number of runs currently queued
|
||||
example: 10
|
||||
paused:
|
||||
type: boolean
|
||||
description: Whether the queue is paused. When paused, no new runs will start.
|
||||
example: false
|
||||
concurrencyLimit:
|
||||
type: integer
|
||||
nullable: true
|
||||
description: The current concurrency limit of the queue
|
||||
example: 10
|
||||
concurrency:
|
||||
type: object
|
||||
description: Detailed concurrency information
|
||||
properties:
|
||||
current:
|
||||
type: integer
|
||||
nullable: true
|
||||
description: The effective/current concurrency limit
|
||||
example: 10
|
||||
base:
|
||||
type: integer
|
||||
nullable: true
|
||||
description: The base concurrency limit defined in code
|
||||
example: 10
|
||||
override:
|
||||
type: integer
|
||||
nullable: true
|
||||
description: The override concurrency limit (if set)
|
||||
example: null
|
||||
overriddenAt:
|
||||
type: string
|
||||
format: date-time
|
||||
nullable: true
|
||||
description: When the concurrency limit was overridden
|
||||
example: null
|
||||
overriddenBy:
|
||||
type: string
|
||||
nullable: true
|
||||
description: Who overrode the concurrency limit (null if via API)
|
||||
example: null
|
||||
ListQueuesResult:
|
||||
type: object
|
||||
required: ["data", "pagination"]
|
||||
properties:
|
||||
data:
|
||||
type: array
|
||||
items:
|
||||
"$ref": "#/components/schemas/QueueObject"
|
||||
description: An array of queue objects
|
||||
pagination:
|
||||
type: object
|
||||
properties:
|
||||
currentPage:
|
||||
type: integer
|
||||
description: The current page number
|
||||
example: 1
|
||||
totalPages:
|
||||
type: integer
|
||||
description: The total number of pages
|
||||
example: 5
|
||||
count:
|
||||
type: integer
|
||||
description: The total number of queues
|
||||
example: 50
|
||||
BatchTriggerRequestBody:
|
||||
type: object
|
||||
properties:
|
||||
|
||||
Reference in New Issue
Block a user