GitLab

GitLab Batched background operations API

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.

Documentation GitHub OpenAPI

Operations 4

GET /api/v4/admin/batched_background_operations Get the list of batched background operations #

GET /api/v4/admin/batched_background_operations/{id} Retrieve a batched background operation #

PUT /api/v4/admin/batched_background_operations/{id}/stop Stop a batched background operation #

PUT /api/v4/admin/batched_background_operations/{id}/restart Restart a batched background operation #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/gitlab:gitlab-batched-background-operations-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: GitLab REST Batched background operations API
  description: GitLab REST API used to interact with a GitLab installation.
  termsOfService: https://handbook.gitlab.com/handbook/legal/api-terms/
  version: '19.6'
  license:
    name: CC BY-SA 4.0
    url: https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE
    x-gitlab-description: The license applies to the OpenAPI specification document itself. For terms governing use of the GitLab API, see the termsOfService field.
servers:
- url: https://{hostname}
  description: GitLab REST API
  variables:
    hostname:
      default: gitlab.com
      description: Your GitLab instance hostname
security:
- http: []
- oauth2: []
- apiKey: []
tags:
- name: Batched background operations
  description: '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.'
  x-displayName: Batched background operations
paths:
  /api/v4/admin/batched_background_operations:
    get:
      operationId: getApiV4AdminBatchedBackgroundOperations
      summary: Get the list of batched background operations
      description: This feature was introduced in GitLab 19.1.
      tags:
      - Batched background operations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIEntitiesBatchedBackgroundOperation'
        '401':
          description: 401 Unauthorized
        '403':
          description: 403 Forbidden
        '400':
          description: Bad Request
      parameters:
      - name: database
        required: false
        description: Name of the database.
        schema:
          type: string
          enum:
          - main
          - ci
          - sec
          - embedding
          - geo
          default: main
        in: query
      - name: job_class_name
        required: false
        description: Filter operations by job class name.
        schema:
          type:
          - string
          - 'null'
        in: query
  /api/v4/admin/batched_background_operations/{id}:
    get:
      operationId: getApiV4AdminBatchedBackgroundOperationsId
      summary: Retrieve a batched background operation
      description: This feature was introduced in GitLab 19.1.
      tags:
      - Batched background operations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesBatchedBackgroundOperation'
        '401':
          description: 401 Unauthorized
        '403':
          description: 403 Forbidden
        '404':
          description: 404 Not found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the batched background operation.
        schema:
          type: integer
        in: path
      - name: database
        required: false
        description: Name of the database.
        schema:
          type: string
          enum:
          - main
          - ci
          - sec
          - embedding
          - geo
          default: main
        in: query
  /api/v4/admin/batched_background_operations/{id}/stop:
    put:
      operationId: putApiV4AdminBatchedBackgroundOperationsIdStop
      summary: Stop a batched background operation
      description: This feature was introduced in GitLab 19.2.
      tags:
      - Batched background operations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesBatchedBackgroundOperation'
        '401':
          description: 401 Unauthorized
        '403':
          description: 403 Forbidden
        '404':
          description: 404 Not found
        '422':
          description: You can stop only `queued`, `active` or `paused` operations.
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the batched background operation.
        schema:
          type: integer
        in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/putApiV4AdminBatchedBackgroundOperationsIdStopRequest'
  /api/v4/admin/batched_background_operations/{id}/restart:
    put:
      operationId: putApiV4AdminBatchedBackgroundOperationsIdRestart
      summary: Restart a batched background operation
      description: This feature was introduced in GitLab 19.2.
      tags:
      - Batched background operations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesBatchedBackgroundOperation'
        '401':
          description: 401 Unauthorized
        '403':
          description: 403 Forbidden
        '404':
          description: 404 Not found
        '422':
          description: You can restart only `stopped` operations.
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the batched background operation.
        schema:
          type: integer
        in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/putApiV4AdminBatchedBackgroundOperationsIdRestartRequest'
components:
  schemas:
    putApiV4AdminBatchedBackgroundOperationsIdStopRequest:
      type: object
      properties:
        database:
          type: string
          enum:
          - main
          - ci
          - sec
          - embedding
          - geo
          description: Name of the database.
          default: main
    APIEntitiesBatchedBackgroundOperation:
      type: object
      properties:
        id:
          type: string
          example: <cluster>:<partition_id>:<id/uuid>
        partition:
          type: integer
          example: 1
        job_class_name:
          type: string
          example: UsersDeleteUnconfirmedSecondaryEmails
        table_name:
          type: string
          example: users
        column_name:
          type: string
          example: id
        status:
          type: string
          example: active
        created_at:
          type: string
          format: date-time
          example: '2025-05-15T10:00:00Z'
        started_at:
          type: string
          format: date-time
          example: '2025-05-15T10:05:00Z'
        finished_at:
          type: string
          format: date-time
          example: '2025-05-15T11:00:00Z'
        on_hold_until:
          type: string
          format: date-time
          example: '2025-05-15T10:15:00Z'
    putApiV4AdminBatchedBackgroundOperationsIdRestartRequest:
      type: object
      properties:
        database:
          type: string
          enum:
          - main
          - ci
          - sec
          - embedding
          - geo
          description: Name of the database.
          default: main
  securitySchemes:
    http:
      type: http
      scheme: bearer
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://gitlab.com/oauth/authorize
          tokenUrl: https://gitlab.com/oauth/token
          refreshUrl: https://gitlab.com/oauth/token
          scopes:
            api: Grants complete read/write access to the API, including all groups and projects, the container registry, the dependency proxy, and the package registry.
            read_api: Grants read access to the API, including all groups and projects, the container registry, and the package registry.
            read_user: Grants read-only access to your profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users.
            create_runner: Grants create access to the runners.
            manage_runner: Grants access to manage the runners.
            k8s_proxy: Grants permission to perform Kubernetes API calls using the agent for Kubernetes.
            self_rotate: Grants permission for token to rotate itself.
            mcp: Grants read-write access to remote Model Context Protocol (MCP) server for tools execution.
            mcp_orbit: Grants access to the Orbit Knowledge Graph MCP server for graph queries and schema retrieval.
    apiKey:
      type: apiKey
      name: PRIVATE-TOKEN
      in: header

GitLab Batched background operations API

Operations 4

Documentation

Specifications

Schemas & Data

Other Resources