---
title: "Override concurrency limit"
method: POST
path: "/api/v1/concurrency-limits/{name}/override"
tags: ["concurrency-limits"]
---

# Override concurrency limit

`POST /api/v1/concurrency-limits/{name}/override`

## Request

- Base URL: `https://api.trigger.dev`
- URL: `https://api.trigger.dev/api/v1/concurrency-limits/{name}/override`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/docs/api/v1/concurrency-limits/:name/override/post.ts> (a function with typed inputs; its response is checked against the schema)

Override a concurrency limit's bounds. Only the given fields change; the declared
values are kept and restored by reset. To stop runs holding a limit, prefer the
pause endpoint (it keeps the configured bounds); overriding `total` to `0` also
blocks every run holding the limit.

## Path parameters

- `name` string, required

## Request body

- union
  - object: Override the limit itself. At least one of `perKey` or `total` must be provided.
    - `perKey` integer: Caps each concurrencyKey pool; runs without a key share one pool. May not exceed the environment concurrency limit.
    - `total` integer: Caps every run holding this limit, keys or not. May not exceed the environment concurrency limit.
  - object: Override the limit's `perKey` for one concurrencyKey only. The override is temporary (see `ttl`), changes no other bound, and applies to every task holding the limit. `total` cannot be given here.
    - `concurrencyKey` string, required: The concurrencyKey whose cap is overridden.
    - `perKey` integer, required: The cap for this key; `0` blocks it. May not exceed the environment concurrency limit.
    - `ttl` union: How long the override lasts, as a duration such as "7d" or a number of seconds. Default 7 days, maximum 30 days.
      - string
      - integer

## Response `200`

Concurrency limit overridden successfully

- union
  - ConcurrencyLimitObject
    - `id` string, required: The limit's id, starting with `climit_`
    - `name` string, required: The limit's name, as declared with `concurrencyLimit()`
    - `perKey` object, required: Caps each concurrencyKey pool; runs without a key share one pool
      - `current` integer, nullable: Enforced right now (null = no per-key bound). Enforcement clamps it to the environment concurrency limit at admit time.
      - `base` integer, nullable: The declared value an override reverts to on reset
      - `override` integer, nullable: The overridden value, when an override is active
      - `overriddenAt` string, date-time, nullable: When the override was applied
    - `total` object, required: Caps every run holding this limit, keys or not
      - `current` integer, nullable: Enforced right now (null = no total bound). Enforcement clamps it to the environment concurrency limit at admit time.
      - `base` integer, nullable: The declared value an override reverts to on reset
      - `override` integer, nullable: The overridden value, when an override is active
      - `overriddenAt` string, date-time, nullable: When the override was applied
    - `running` integer, required: Runs executing that hold this limit
    - `queued` integer, required: Runs that are queued and must clear this limit to execute
    - `paused` boolean: Whether the limit is paused. A paused limit admits no runs until resumed; its configured bounds are kept.
  - ConcurrencyLimitKeyObject: A limit's view for one concurrencyKey, returned when a request names a concurrencyKey.
    - `name` string, required: The limit's name, as declared with `concurrencyLimit()`
    - `concurrencyKey` string, required: The concurrencyKey this view is for
    - `perKey` object, required: The per-key bound for this key
      - `current` integer, nullable: Enforced right now for this key (the override when one is in force, else the limit's perKey), clamped to the environment concurrency limit
      - `base` integer, nullable: The limit's own perKey as enforced
      - `override` integer, nullable: The key's temporary override, when one is in force
      - `expiresAt` string, date-time, nullable: When the key's override lapses; null when there is none
    - `running` integer, required: Runs executing for this key that hold this limit
    - `paused` boolean, required: Whether the limit is paused. A paused limit admits no runs, override or not.

## Other responses

- `400`: Invalid request parameters, or a bound exceeds the environment concurrency limit
- `401`: Unauthorized request
- `404`: Concurrency limit not found
- `409`: The limit changed concurrently; retry the request

## Changes

- **2026-10-13** `ed63702553ec`: 9 breaking, 3 warning, 1 info
  - the request's body type changed from `object` to no type
  - added `#/components/schemas/ConcurrencyLimitObject, #/components/schemas/ConcurrencyLimitKeyObject` to the response body `oneOf` list for the response status `200`
  - the response's body type changed from `object` to no type for status `200`
  - removed the required property `id` from the response with the `200` status
  - …9 more
- **2026-09-20** `6f90f61d7598`: 1 info
  - added the optional property `paused` to the response with the `200` status
- **2026-09-18** `f16898f8f42a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/changes/api/v1/concurrency-limits/:name/override/post.md)

---

[API](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api.md) - [All operations](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/revisions/441161111493?raw)