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

# Rate and concurrency limits

> How many runs can be active at once on each plan, which requests are limited per minute, and how to handle a 429.

Limits keep one caller from taking all of a deployment's capacity. The main one is how many runs can be active at the same time. A few kinds of request are also limited per minute. Past a limit you get `429 Too Many Requests`.

## Runs at the same time

A run counts while it is `queued` or `running`. A run paused at `awaiting_input` does not count. The limits apply per person and per organization.

The runs of an API key count against the person who created the key. Changing `name` or `email` on `POST /chat` does not change the count.

### SaaS

| Plan | Per person | Per organization |
| - | - | - |
| **Free** | 1 | |
| **Pro** | 10 | |
| **Business** | 30 | 30 |

**Free** has no API keys, but its limit still applies to the web app. See [Plans and limits](https://docs.neuralfactory.ai/user-guide/admin/billing.md) for the rest of each plan.

### Enterprise

By default, 10 runs per person and 25 per organization. Your deployment can set other values, and an Admin can give one member a different per-person limit with `PUT /admin/concurrency/members/{user_id}` and the body `{"max_concurrent_agent_runs": 15}` (a key needs **Admin**). Sending `null` or `0` removes the member's own limit, and the default applies again.

### Past the limit

`POST /chat` answers `429` with a `Retry-After` header of 30 seconds. On SaaS, resuming a paused run takes a place again, so `POST /runs/{run_id}/resume` can answer the same `429`.

```
HTTP/1.1 429 Too Many Requests
Retry-After: 30

{"detail": "You already have 10 agent runs in progress (your limit is 10). Please wait for one to finish."}
```

| Limit reached | `detail` |
| - | - |
| Per person, Enterprise | `You already have N agent runs in progress (your limit is N). Please wait for one to finish.` |
| Per person, SaaS | `You already have N agent runs in progress (your limit is N). Wait for one to finish, or upgrade your plan for more parallel tasks.` |
| Per organization | `Your organization already has N agent runs in progress (limit N). Please wait for one to finish.` |

## Workflow runs at the same time

Workflow runs have a limit of their own, counted separately from the agent runs of `POST /chat`:

* **Enterprise**: 25 workflow runs in progress per organization, by default.
* **SaaS**: the plan's runs at a time from the table above: the organization's limit for an organization, the person's for a personal account.

Past it, starting a workflow run answers `429` with `Retry-After: 30` and `You already have N workflow runs in progress (limit N). Please wait for one to finish and try again shortly.`

## Requests per minute

These requests are counted per minute, in fixed one-minute windows. An API key has its own count, separate from the web app traffic of the person who made it.

| What | Per key or person | Per organization |
| - | - | - |
| Starting workflow runs | 30 a minute | 300 a minute |
| Building or refining a workflow (`POST /builds` with `kind: "workflow"`) | 10 a minute | |
| Building or refining an agent (`POST /builds` with `kind: "agent"`) | 10 a minute | |

These are the defaults; a deployment can change them. Past a limit you get `429` with `Retry-After` set to the seconds left in the current minute, and a body like this:

```json theme={null}
{ "detail": { "reason": "rate_limited", "scope": "workflow_runs", "retry_after_seconds": 12 } }
```

`scope` names the limit: `workflow_runs`, `workflow_compile` or `agent_compile`.

## Runs started per hour

A deployment can also limit how many runs an organization starts per hour. This limit is off by default. When it is on and reached, `POST /chat` answers `429` with `Retry-After: 300` and `Your organization has started N agent runs in the last hour (limit N). Please wait before starting more.`

## Usage and spend limits

A `429` can also mean the usage you may spend is used up, or a spend limit is reached. Those answers have no `Retry-After`, because waiting a few seconds does not clear them. The messages are on [Errors](https://docs.neuralfactory.ai/api-reference/errors.md#account-and-usage-saas).

## Handle a 429

1. If the answer has `Retry-After`, wait that many seconds before you retry.
2. For a run limit, you can also wait for one of your runs to end. [Poll](https://docs.neuralfactory.ai/api-reference/runs.md#poll-a-run) or [stream](https://docs.neuralfactory.ai/api-reference/streaming.md) it, or use a [webhook](https://docs.neuralfactory.ai/api-reference/webhooks.md).
3. Retry with the same `idempotency_key`, so a retry never starts a second run.
4. If there is no `Retry-After`, do not retry in a loop. Read `detail`: an Admin has to act, for example by buying a top-up or raising a limit.

To do more work in parallel, spread it over separate conversations (`chat_id`s) within these limits. A conversation runs one turn at a time.

## Related

* [Runs and results](https://docs.neuralfactory.ai/api-reference/runs.md)
* [Errors](https://docs.neuralfactory.ai/api-reference/errors.md)
* [Plans and limits](https://docs.neuralfactory.ai/user-guide/admin/billing.md)


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