Sidekiq queues administration API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed, GitLab Dedicated

Delete jobs from a Sidekiq queue

Deletes jobs from a Sidekiq queue that match the given metadata.

The response has three fields:

  1. deleted_jobs - the number of jobs deleted by the request.
  2. queue_size - the remaining size of the queue after processing the request.
  3. completed - whether or not the request was able to process the entire queue in time. If not, retrying with the same parameters may delete further jobs (including those added after the first request was issued).

This API endpoint is only available to administrators.

DELETE /admin/sidekiq/queues/:queue_name
AttributeTypeRequiredDescription
queue_namestringyesThe name of the queue to delete jobs from
userstringnoThe username of the user who scheduled the jobs
projectstringnoThe full path of the project where the jobs were scheduled from
root_namespacestringnoThe root namespace of the project
subscription_planstringnoThe subscription plan of the root namespace (GitLab.com only)
caller_idstringnoThe endpoint or background job that scheduled the job (for example: ProjectsController#create, /api/:version/projects/:id, PostReceive)
feature_categorystringnoThe feature category of the background job (for example: team_planning or code_review)
client_typestringnoThe kind of client whose request scheduled the jobs (for example: browser, ide, or mobile)
client_namestringnoThe client whose request scheduled the jobs (for example: vscode or gitlab-mobile-ios)
client_versionstringnoThe release of the client whose request scheduled the jobs (for example: 6.21.0 or 1.2.0)
worker_classstringnoThe class of the background job worker (for example: PostReceive or MergeWorker)

At least one attribute, other than queue_name, is required.

Example request:

shell
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/admin/sidekiq/queues/:queue_name"

Example response:

json
{
  "completed": true,
  "deleted_jobs": 7,
  "queue_size": 14
}

Manage Sidekiq worker concurrency limits

These administrator-only endpoints inspect, set, and clear temporary concurrency overrides for registered Sidekiq workers.

A positive override takes precedence over adaptive throttling and the class default. Pausing takes precedence over an override. Disabled concurrency middleware ignores overrides.

When an override expires or is cleared, the stored adaptive limit resumes if it remains valid. Otherwise, the worker’s runtime default applies. Lowering a limit does not terminate running jobs.

Retrieve a worker concurrency limit

GET /admin/sidekiq/concurrency_limits/:worker_class

Returns the worker’s concurrency-limit status.

AttributeTypeRequiredDescription
worker_classstringYesRegistered worker class name.

Example request:

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/admin/sidekiq/concurrency_limits/Namespace::ExampleWorker"

Replace Namespace::ExampleWorker with a registered worker name. Namespaced names keep the :: separator in the path.

If successful, returns 200 OK and the following response attributes:

AttributeTypeDescription
adaptive_limitinteger or nullStored adaptive limit, or null when absent.
class_limitinteger or nullExplicit class limit. null when the worker has no explicit limit.
default_limit_requires_shard_contextbooleanWhether the default is derived from shard size and cannot be reported outside a Sidekiq process. false when sidekiq_concurrency_limit_default_calculation is disabled, because the default is then 0.
deferred_jobsintegerApproximate deferred job count.
disabled_for_workerbooleanWhether the worker-specific bypass flag disables enforcement in the client and server middleware.
effective_limitinteger or nullEffective limit. Zero means unlimited. Negative values mean paused. null means unknown without shard context.
middleware_enabledbooleanWhether concurrency middleware is enabled.
override_limitinteger or nullTemporary override, or null when absent.
override_ttlinteger or nullRemaining override lifetime in seconds, or null when absent.
running_jobsintegerApproximate running job count.
worker_classstringRegistered worker class name.

Example response:

json
{
  "worker_class": "Namespace::ExampleWorker",
  "class_limit": 10,
  "effective_limit": 20,
  "adaptive_limit": 6,
  "override_limit": 20,
  "override_ttl": 1800,
  "default_limit_requires_shard_context": false,
  "middleware_enabled": true,
  "disabled_for_worker": false,
  "running_jobs": 4,
  "deferred_jobs": 100
}

Update a worker concurrency override

PUT /admin/sidekiq/concurrency_limits/:worker_class

Sets or replaces a temporary concurrency override. The worker must not be paused. Workers without a limit can receive a temporary cap. Replacing an override restarts its time to live (TTL).

AttributeTypeRequiredDescription
worker_classstringYesRegistered worker class name.
limitintegerYesPositive concurrency limit. Zero and negative values are rejected.
ttlintegerNoLifetime in seconds, from 1 to 86400. Defaults to 1800.

Example request:

shell
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{"limit":20,"ttl":1800}' \
  --url "https://gitlab.example.com/api/v4/admin/sidekiq/concurrency_limits/ExampleWorker"

Returns 200 OK with the concurrency-limit status fields and example response.

Returns 400 Bad Request when:

  • limit is zero or negative, or ttl is outside 1 to 86400.
  • The worker is paused.
  • The sidekiq_concurrency_limit_middleware feature flag is disabled.
  • The worker’s disable_sidekiq_concurrency_limit_middleware_<WorkerClass> bypass flag is enabled.
  • The worker is ConcurrencyLimit::ResumeWorker, which resumes deferred jobs and cannot be limited.

Delete a worker concurrency override

DELETE /admin/sidekiq/concurrency_limits/:worker_class

Clears the temporary override and returns the updated concurrency-limit status.

AttributeTypeRequiredDescription
worker_classstringYesRegistered worker class name.

Example request:

shell
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/admin/sidekiq/concurrency_limits/ExampleWorker"

Returns 200 OK with the concurrency-limit status fields.

Example response:

json
{
  "worker_class": "ExampleWorker",
  "class_limit": 10,
  "effective_limit": 6,
  "adaptive_limit": 6,
  "override_limit": null,
  "override_ttl": null,
  "default_limit_requires_shard_context": false,
  "middleware_enabled": true,
  "disabled_for_worker": false,
  "running_jobs": 4,
  "deferred_jobs": 100
}

All concurrency-limit endpoints return 404 Not Found for unregistered workers, 401 Unauthorized for unauthenticated requests, and 403 Forbidden for non-administrators.