Concurrency & Queues

When you trigger a task, it isn’t executed immediately. Instead, the task run is placed into a queue for execution. By default, each task gets its own queue and the concurrency is only limited by your environment concurrency limit. If you need more control (for example, to limit concurrency or share limits across multiple tasks), you can define a custom queue as described later. Controlling concurrency is useful when you have a task that can’t be run concurrently, or when you want to limit the number of runs to avoid overloading a resource. It’s important to note that only actively executing runs count towards concurrency limits. Runs that are delayed or waiting in a queue do not consume concurrency slots until they begin execution.

Default concurrency

By default, all tasks have an unbounded concurrency limit, limited only by the overall concurrency limits of your environment.

Your environment has a base concurrency limit and a burstable limit (default burst factor of 2.0x the base limit). Individual queues are limited by the base concurrency limit, not the burstable limit. For example, if your base limit is 10, your environment can burst up to 20 concurrent runs, but any single queue can have at most 10 concurrent runs. If you’re a paying customer you can request higher burst limits by contacting us.

Setting task concurrency

You can set the concurrency limit for a task by setting the concurrencyLimit property on the task’s queue. This limits the number of runs that can be executing at any one time:

/trigger/one-at-a-time.ts

// This task will only run one at a time
export const oneAtATime = task({
  id: "one-at-a-time",
  queue: {
    concurrencyLimit: 1,
  },
  run: async (payload) => {
    //...
  },
});

This is useful if you need to control access to a shared resource, like a database or an API that has rate limits. As well as putting queue settings directly on a task, you can define a queue and reuse it across multiple tasks. This allows you to share the same concurrency limit:

/trigger/queue.ts

export const myQueue = queue({
  name: "my-queue",
  concurrencyLimit: 1,
});

export const task1 = task({
  id: "task-1",
  queue: myQueue,
  run: async (payload: { message: string }) => {
    // ...
  },
});

export const task2 = task({
  id: "task-2",
  queue: myQueue,
  run: async (payload: { message: string }) => {
    // ...
  },
});

In this example, task1 and task2 share the same queue, so only one of them can run at a time.

Setting the queue when you trigger a run

When you trigger a task you can override the default queue. This is really useful if you sometimes have high priority runs. The task and queue definition:

/trigger/override-concurrency.ts

const paidQueue = queue({
  name: "paid-users",
  concurrencyLimit: 10,
});

export const generatePullRequest = task({
  id: "generate-pull-request",
  queue: {
    //normally when triggering this task it will be limited to 1 run at a time
    concurrencyLimit: 1,
  },
  run: async (payload) => {
    //todo generate a PR using OpenAI
  },
});

Triggering from your backend and overriding the queue:

app/api/push/route.ts

import { generatePullRequest } from "~/trigger/override-concurrency";

export async function POST(request: Request) {
  const data = await request.json();

  if (data.branch === "main") {
    //trigger the task, with the paid users queue
    const handle = await generatePullRequest.trigger(data, {
      // Set the paid users queue
      queue: "paid-users",
    });

    return Response.json(handle);
  } else {
    //triggered with the default queue (concurrency of 1)
    const handle = await generatePullRequest.trigger(data);
    return Response.json(handle);
  }
}

Concurrency keys and per-tenant queuing

If you’re building an application where you want to run tasks for your users, you might want a separate queue for each of your users (or orgs, projects, etc.). You can do this by using concurrencyKey. It creates a copy of the queue for each unique value of the key. Your backend code:

app/api/pr/route.ts

import { generatePullRequest } from "~/trigger/override-concurrency";

export async function POST(request: Request) {
  const data = await request.json();

  if (data.isFreeUser) {
    //the "free-users" queue has a concurrency limit of 1
    const handle = await generatePullRequest.trigger(data, {
      queue: "free-users",
      //this creates a free-users queue for each user
      concurrencyKey: data.userId,
    });

    //return a success response with the handle
    return Response.json(handle);
  } else {
    //the "paid-users" queue has a concurrency limit of 10
    const handle = await generatePullRequest.trigger(data, {
      queue: "paid-users",
      //this creates a paid-users queue for each user
      concurrencyKey: data.userId,
    });

    //return a success response with the handle
    return Response.json(handle);
  }
}

Concurrency and subtasks

When you trigger a task that has subtasks, the subtasks will not inherit the queue from the parent task. Unless otherwise specified, subtasks will run on their own queue

/trigger/subtasks.ts

export const parentTask = task({
  id: "parent-task",
  run: async (payload) => {
    //trigger a subtask
    await subtask.triggerAndWait(payload);
  },
});

// This subtask will run on its own queue
export const subtask = task({
  id: "subtask",
  run: async (payload) => {
    //...
  },
});

Waits and concurrency

With our task checkpoint system, tasks can wait at various waitpoints (like waiting for subtasks to complete, delays, or external events). The way this system interacts with the concurrency system is important to understand. Concurrency is only released when a run reaches a waitpoint and is checkpointed. When a run is checkpointed, it transitions to the WAITING state and releases its concurrency slot back to both the queue and the environment, allowing other runs to execute or resume. This means that:

Only actively executing runs count towards concurrency limits
Runs in the WAITING state (checkpointed at waitpoints) do not consume concurrency slots
You can have more runs in the WAITING state than your queue’s concurrency limit
When a waiting run resumes (e.g., when a subtask completes), it must re-acquire a concurrency slot

For example, if you have a queue with a concurrencyLimit of 1:

You can only have exactly 1 run executing at a time
You may have multiple runs in the WAITING state that belong to that queue
When the executing run reaches a waitpoint and checkpoints, it releases its slot
The next queued run can then begin execution

Waiting for a subtask on a different queue

When a parent task triggers and waits for a subtask on a different queue, the parent task will checkpoint and release its concurrency slot once it reaches the wait point. This prevents environment deadlocks where all concurrency slots would be occupied by waiting tasks.

/trigger/waiting.ts

export const parentTask = task({
  id: "parent-task",
  queue: {
    concurrencyLimit: 1,
  },
  run: async (payload) => {
    //trigger a subtask and wait for it to complete
    await subtask.triggerAndWait(payload);
    // The parent task checkpoints here and releases its concurrency slot
    // allowing other tasks to execute while waiting
  },
});

export const subtask = task({
  id: "subtask",
  run: async (payload) => {
    //...
  },
});

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:

import { queues } from "@trigger.dev/sdk";

Listing queues

You can list all queues in your environment with pagination support:

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:

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:

{
  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.

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:

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:

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:

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" });

Getting started

Fundamentals

Building with AI

Writing tasks

Agents

Configuration

Deployment

Private networking

Realtime

CLI

Observability

Using the Dashboard

Troubleshooting

Self-hosting

Open source

Help

Default concurrency

Setting task concurrency

Setting the queue when you trigger a run

Concurrency keys and per-tenant queuing

Concurrency and subtasks

Waits and concurrency

Waiting for a subtask on a different queue

Managing queues with the SDK

Listing queues

Retrieving a queue

Pausing and resuming queues

Overriding concurrency limits

​Default concurrency

​Setting task concurrency

​Sharing concurrency between tasks

​Setting the queue when you trigger a run

​Concurrency keys and per-tenant queuing

​Concurrency and subtasks

​Waits and concurrency

​Waiting for a subtask on a different queue

​Managing queues with the SDK

​Listing queues

​Retrieving a queue

​Pausing and resuming queues

​Overriding concurrency limits

Default concurrency

Setting task concurrency

Sharing concurrency between tasks

Setting the queue when you trigger a run

Concurrency keys and per-tenant queuing

Concurrency and subtasks

Waits and concurrency

Waiting for a subtask on a different queue

Managing queues with the SDK

Listing queues

Retrieving a queue

Pausing and resuming queues

Overriding concurrency limits