From 6ffd3afb629bfd584aedf9af422a9c2c4602dee5 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Feb 2026 21:35:05 +0000 Subject: [PATCH] docs: add documentation for queue management SDK functions and API Added documentation for the previously undocumented queue management functions in the SDK `queues` namespace: - queues.list() - List all queues with pagination - queues.retrieve() - Retrieve a queue by ID or type/name - queues.pause() - Pause a queue - queues.resume() - Resume a paused queue - queues.overrideConcurrencyLimit() - Override concurrency limit - queues.resetConcurrencyLimit() - Reset concurrency limit Changes: - Updated queue-concurrency.mdx with SDK function documentation - Added OpenAPI endpoints for all queue management APIs - Created API reference pages in docs/management/queues/ - Added Queues API group to docs.json navigation Slack thread: https://triggerdotdev.slack.com/archives/C061L2MHW93/p1771450098057739 https://claude.ai/code/session_01LyrXwxHCbejvi34fykifPP --- docs/docs.json | 10 + .../queues/concurrency-override.mdx | 4 + docs/management/queues/concurrency-reset.mdx | 4 + docs/management/queues/list.mdx | 4 + docs/management/queues/pause.mdx | 4 + docs/management/queues/retrieve.mdx | 4 + docs/queue-concurrency.mdx | 126 ++++++ docs/v3-openapi.yaml | 386 ++++++++++++++++++ 8 files changed, 542 insertions(+) create mode 100644 docs/management/queues/concurrency-override.mdx create mode 100644 docs/management/queues/concurrency-reset.mdx create mode 100644 docs/management/queues/list.mdx create mode 100644 docs/management/queues/pause.mdx create mode 100644 docs/management/queues/retrieve.mdx diff --git a/docs/docs.json b/docs/docs.json index 5c2bddede0c..23449775883 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -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": [ diff --git a/docs/management/queues/concurrency-override.mdx b/docs/management/queues/concurrency-override.mdx new file mode 100644 index 00000000000..de62d91c950 --- /dev/null +++ b/docs/management/queues/concurrency-override.mdx @@ -0,0 +1,4 @@ +--- +title: "Override Concurrency Limit" +openapi: "v3-openapi POST /api/v1/queues/{queueParam}/concurrency/override" +--- diff --git a/docs/management/queues/concurrency-reset.mdx b/docs/management/queues/concurrency-reset.mdx new file mode 100644 index 00000000000..7e790e21e45 --- /dev/null +++ b/docs/management/queues/concurrency-reset.mdx @@ -0,0 +1,4 @@ +--- +title: "Reset Concurrency Limit" +openapi: "v3-openapi POST /api/v1/queues/{queueParam}/concurrency/reset" +--- diff --git a/docs/management/queues/list.mdx b/docs/management/queues/list.mdx new file mode 100644 index 00000000000..e74b9dfe1e6 --- /dev/null +++ b/docs/management/queues/list.mdx @@ -0,0 +1,4 @@ +--- +title: "List Queues" +openapi: "v3-openapi GET /api/v1/queues" +--- diff --git a/docs/management/queues/pause.mdx b/docs/management/queues/pause.mdx new file mode 100644 index 00000000000..2f684459b17 --- /dev/null +++ b/docs/management/queues/pause.mdx @@ -0,0 +1,4 @@ +--- +title: "Pause or Resume Queue" +openapi: "v3-openapi POST /api/v1/queues/{queueParam}/pause" +--- diff --git a/docs/management/queues/retrieve.mdx b/docs/management/queues/retrieve.mdx new file mode 100644 index 00000000000..3410e6d89d1 --- /dev/null +++ b/docs/management/queues/retrieve.mdx @@ -0,0 +1,4 @@ +--- +title: "Retrieve Queue" +openapi: "v3-openapi GET /api/v1/queues/{queueParam}" +--- diff --git a/docs/queue-concurrency.mdx b/docs/queue-concurrency.mdx index fc4829757dc..24e77f4e67f 100644 --- a/docs/queue-concurrency.mdx +++ b/docs/queue-concurrency.mdx @@ -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. + + + Import from `@trigger.dev/sdk`: + ```ts + import { queues } from "@trigger.dev/sdk"; + ``` + + +### 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" }); +``` diff --git a/docs/v3-openapi.yaml b/docs/v3-openapi.yaml index 2fdcd0afd9d..1ce1a80f659 100644 --- a/docs/v3-openapi.yaml +++ b/docs/v3-openapi.yaml @@ -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: