Skip to content

Set a job type's concurrency limit

PUT
/admin/jobs/concurrency/{type}

Saves the concurrency limit for one background job type.

You need to be signed in with system.admin for the whole install; a permission held only for a team doesn’t count, and system.jobs.read doesn’t allow this action.

Send an integer cap from 0 through 64. A positive value saves that type’s limit; zero deletes the setting and removes its per-type limit. The type name is used exactly as sent: it isn’t trimmed or checked against registered handlers, and saving a limit doesn’t register a handler.

The setting applies within each application process’s worker pool once that process restarts and loads its settings successfully. It doesn’t update running pools or limit external-worker claims. When cap is zero, the pool’s overall worker count still limits local execution.

The request schema marks cap as required, but the current decoder treats an omitted or null cap, an empty object or a JSON null body as zero, which clears the setting. An empty or malformed body gets a plain-text 400, even when you aren’t signed in, and negative values or values above 64 get 400. This decoder doesn’t check unknown properties or anything after the first JSON value.

A 204 confirms the setting was saved or cleared, not that a running pool picked it up. Concurrent writes to the same type have no version check: the last committed setting wins, and a retry can overwrite another administrator’s change. Each type name has its own row.

type
required
string

Job type name, such as preview.video. The handler doesn’t check it against registered types.

The setting for one job type. A positive value saves a limit; zero removes it.

object
cap
required

Integer from 0 through 64; zero clears the saved per-type limit. The schema marks it required, but an omitted or null value currently also decodes as zero. Each application process must restart and load its settings successfully for a change to apply.

integer
<= 64

The setting was saved or cleared. Existing worker pools have not been updated.

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed