> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nelkap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Concurrency

> Set how many runs of a workflow may go 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 go at once, the others wait their turn, and none is lost.

## Set a limit

Set `concurrency` when you register the workflow:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
nelkap.registerWorkflows([
  {
    name: 'importContacts',
    handler: importContacts,
    concurrency: 5,
  },
]);
```

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

## 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 run that was waiting 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, set by your plan, on the runs going at once across all its workflows. A workflow without `concurrency` only has that limit. A workflow with one gets whichever is lower. See [Limits](https://docs.nelkap.com/limits.md#by-plan).

## 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 going: 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 go 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:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
nelkap.registerWorkflows([
  {
    name: 'syncCatalog',
    handler: syncCatalog,
    cron: '0 2 * * *',
    concurrency: 1,
  },
]);
```

The limit applies to the whole workflow, not to each customer. Two runs for different customers also wait for each other.

## Queue metrics

The Metrics page charts the runs waiting to start, the runs going at once, and how long runs wait before they start. A backlog that keeps growing means the limit is lower than the work coming in. See [Metrics](https://docs.nelkap.com/monitor/metrics.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.