Concurrency

When you trigger a task, the run waits in a queue and runs start in trigger order as capacity allows. Concurrency is what decides how much capacity there is. By default, 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 set a concurrency limit on the task, or declare a named limit and share it, as described below. 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.

Use cases

Limit how many runs of a task execute at once: Setting task concurrency
Share one limit across several tasks: Sharing a limit between tasks
Give each tenant its own separate concurrency: Concurrency keys and per-tenant limits
Per-tenant limits with a ceiling on the total: Per-key and total limits together
Cap a tenant across every task they run: A per-tenant cap across multiple tasks
Cap a shared resource, like an external API, across tasks and tenants: A global cap for a shared resource
Switch a run’s limits when you trigger it: Setting limits when you trigger a run

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 tasks and limits are capped 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 limit can allow at most 10 concurrent runs. If you’re a paying customer you can request higher burst limits by contacting us.

Setting task concurrency

Set the concurrency option on a task to limit how many of its runs execute at once. { total: n } caps the task outright:

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

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

// This task will only run one at a time
export const oneAtATime = task({
  id: "one-at-a-time",
  concurrency: { total: 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. There are two ways to bound a task, and you can combine them:

total caps every run of the task together, whether or not runs use a concurrencyKey.
perKey caps each concurrencyKey pool separately; runs triggered without a key share one pool.

/trigger/per-user.ts

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

export const generateReport = task({
  id: "generate-report",
  // each user runs at most 1 at a time, and at most 10 run in total
  concurrency: { perKey: 1, total: 10 },
  run: async (payload) => {
    //...
  },
});

The queue: {"{ concurrencyLimit: n }"} option keeps working but is deprecated in favor of concurrency. Its single number means “per key when runs pass a concurrencyKey, whole queue when they don’t” — the concurrency shape says which you mean explicitly.

Declare a named limit with concurrencyLimit() and put it in each task’s concurrency. Every task holding the limit draws from the same pools:

/trigger/limits.ts

import { concurrencyLimit, task } from "@trigger.dev/sdk";

// at most 25 concurrent runs across every task that holds this limit
export const openaiLimit = concurrencyLimit({ name: "openai", total: 25 });

export const generateSummary = task({
  id: "generate-summary",
  concurrency: openaiLimit,
  run: async (payload) => {
    // ...
  },
});

export const generateTitle = task({
  id: "generate-title",
  concurrency: openaiLimit,
  run: async (payload) => {
    // ...
  },
});

A task’s concurrency takes a single item or an array: at most one inline shape (which caps that task alone) plus up to two named limits. A run starts only when every limit it holds has capacity, and it occupies a slot in each while it executes:

/trigger/summarize.ts

import { concurrencyLimit, task } from "@trigger.dev/sdk";

export const openaiLimit = concurrencyLimit({ name: "openai", total: 25 });

export const summarizeThread = task({
  id: "summarize-thread",
  // this task runs at most 5 at once, and also counts towards the shared openai limit
  concurrency: [{ total: 5 }, openaiLimit],
  run: async (payload) => {
    // ...
  },
});

Names you declare with concurrencyLimit() are 1-122 characters using only letters, numbers, underscores and hyphens.

Setting limits when you trigger a run

The trigger-time concurrency option takes limit names and replaces the task’s declared named limits for that run. The task’s inline limit always applies:

app/api/report/route.ts

import { generateReport } from "~/trigger/reports";

// this run counts towards "priority" instead of the task's declared named limits
await generateReport.trigger(data, { concurrency: ["priority"] });

Pass an empty array to run with only the task’s inline limit.

Concurrency keys and per-tenant limits

If you’re building an application where you want to run tasks for your users, you might want a separate limit for each of your users (or orgs, projects, etc.). You can do this by passing a concurrencyKey when you trigger. Each unique key value gets its own pool under every perKey bound the run holds:

app/api/report/route.ts

import { generateReport } from "~/trigger/per-user";

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

  const handle = await generateReport.trigger(data, {
    // every user gets their own concurrency pool

Getting started

Fundamentals

Building with AI

Writing tasks

Agents

Webhooks

Configuration

Deployment

Private networking

Realtime

CLI

Observability

Using the Dashboard

Troubleshooting

Self-hosting

Open source

Help

Use cases

Default concurrency

Setting task concurrency

Setting limits when you trigger a run

Concurrency keys and per-tenant limits

​Use cases

​Default concurrency

​Setting task concurrency

​Sharing a limit between tasks

​Setting limits when you trigger a run

​Concurrency keys and per-tenant limits

Use cases

Default concurrency

Setting task concurrency

Sharing a limit between tasks

Setting limits when you trigger a run

Concurrency keys and per-tenant limits