Use this API to list, retrieve, restart, and stop the batched background operations running on an instance.
These endpoints require administrator access to the instance.
Get the list of batched background operations
GET /api/v4/admin/batched_background_operations
This feature was introduced in GitLab 19.1.
Parameters
| Name | Type | Description |
|---|---|---|
databaseQuery | String | The name of the database,mainAllowed values: main,ci,secDefault: main |
job_Query | String | Filter operations by job class name |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
401 | 401 Unauthorized | — |
403 | 403 Forbidden | — |
Retrieve a batched background operation
GET /api/v4/admin/batched_background_operations/{id}
This feature was introduced in GitLab 19.1.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | Integer | The batched background operation id |
databaseQuery | String | The name of the database Allowed values: main,ci,secDefault: main |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
401 | 401 Unauthorized | — |
403 | 403 Forbidden | — |
404 | 404 Not found | — |
Restart a batched background operation
PUT /api/v4/admin/batched_background_operations/{id}/restart
This feature was introduced in GitLab 19.2.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | Integer | The batched background operation id |
Request body (application/json)
| Property | Type | Description |
|---|---|---|
database | String | The name of the database Allowed values: main,ci,secDefault: main |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
401 | 401 Unauthorized | — |
403 | 403 Forbidden | — |
404 | 404 Not found | — |
422 | You can restart only stopped operations. | — |
Stop a batched background operation
PUT /api/v4/admin/batched_background_operations/{id}/stop
This feature was introduced in GitLab 19.2.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | Integer | The batched background operation id |
Request body (application/json)
| Property | Type | Description |
|---|---|---|
database | String | The name of the database Allowed values: main,ci,secDefault: main |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
401 | 401 Unauthorized | — |
403 | 403 Forbidden | — |
404 | 404 Not found | — |
422 | You can stop only queued,active or paused operations. | — |
Schemas
Objects returned by the operations above and objects nested in their request bodies.
APIEntitiesBatchedBackgroundOperation
| Property | Type | Description |
|---|---|---|
column_ | String | Example:id |
created_ | String (date- | Example:2025- |
finished_ | String (date- | Example:2025- |
id | String | Example:<cluster>: |
job_ | String | Example:Users |
on_ | String (date- | Example:2025- |
partition | Integer | Example:1 |
started_ | String (date- | Example:2025- |
status | String | Example:active |
table_ | String | Example:users |