Concurrency

Set how many runs of a workflow may execute at once, so a burst of work never overwhelms your app or the services it calls.

A thousand sign-ups in a minute start a thousand runs. If each one calls a partner’s API that accepts five requests at a time, most of them fail. With a concurrency limit, five runs execute at once, the others wait their turn, and none is lost.

Set a limit

Set concurrency when you register the workflow:

nelkap/index.ts

nelkap.registerWorkflows([
  {
    name: 'importContacts',
    handler: importContacts,
    concurrency: 5,
  },
]);

At most five runs of importContacts execute at once. The limit is a whole number from 1 to 500.

Use cases

Need	Setting
Stay under what another service accepts, like a partner API that takes five requests at a time.	concurrency: 5 on the workflow that calls it.
Spread the load of a big job, like the batches of an import that all write to your database.	A low limit on the workflow that runs each batch.
Never let two runs overlap, like a nightly sync.	concurrency: 1. See Sequential runs.

Counted runs

A run counts toward the limit from the moment it’s sent to your app until it pauses or ends:

• A run on its way to your app, or running in it, counts.
• A sleeping or waiting run doesn’t, since nothing runs while it’s paused. It counts again once it wakes up and goes back to your app.
• A pending run doesn’t count yet. It’s the one waiting for its turn.

So a limit caps the work your app does at the same time, not the number of runs in progress.

Queue order

Runs over the limit stay pending, and take their turn in the order they were created: the oldest goes first. Nelkap hands out free turns every minute, so a waiting run starts within a minute after a turn frees up.

A run woken from a sleep or a wait waits for a turn too. It keeps its place by creation date, so it goes ahead of runs created after it.

Workspace limit

Your workspace also has a limit on the runs executing at once across all its workflows: 50, 100, or 500, depending on your plan. A workflow without concurrency only has that limit. A workflow with one gets whichever is lower. See Limits.

Change a limit

The limit you register replaces the old one at once. Raising it lets more runs start on the next minute. Lowering it never stops a run already executing: the runs over the new limit finish, and no new run starts until the count falls below it.

To remove a limit, register the workflow without concurrency.

Sequential runs

With concurrency: 1, the runs of a workflow execute one after the other, in the order they were created. That’s useful for work that must never overlap, like a nightly sync that shouldn’t start before the previous one ended:

nelkap/index.ts

nelkap.registerWorkflows([
  {
    name: 'syncCatalog',
    handler: syncCatalog,
    cron: '0 2 * * *',
    concurrency: 1,
  },
]);

The limit applies to the whole workflow, not to each customer. With concurrency: 1, two runs for different customers also wait for each other.

Queue metrics

On the Metrics page, the Backlog chart shows the runs waiting to start, Concurrency the runs executing at once, and Latency how long runs wait before they start. A backlog that keeps growing means the limit is lower than the work coming in. See Metrics.