GitLab Jobs API

openapi: 3.2.0
info:
  title: GitLab REST Jobs 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: Jobs
  description: 'Use this API to run CI/CD jobs on a runner: request the next

    job, update its state, append to its log, and transfer its artifacts.


    GitLab Runner uses these endpoints itself.'
  x-displayName: Jobs
paths:
  /api/v4/runners/{id}/jobs:
    get:
      operationId: getApiV4RunnersIdJobs
      summary: List all jobs processed by a runner
      description: Lists all jobs that are being processed or were processed by a specified runner. The list of jobs is limited to projects where the user has the Reporter, Developer, Maintainer, or Owner role.
      tags:
      - Jobs
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesCiJobBasicWithProject'
        '401':
          description: Unauthorized
        '403':
          description: No access granted
        '404':
          description: Runner not found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the runner.
        schema:
          type: integer
        in: path
      - name: system_id
        required: false
        description: System ID associated with the runner manager.
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: status
        required: false
        description: Status of the job.
        schema:
          type:
          - string
          - 'null'
          enum:
          - created
          - waiting_for_resource
          - preparing
          - waiting_for_callback
          - pending
          - running
          - success
          - failed
          - canceling
          - canceled
          - skipped
          - manual
          - scheduled
          - null
        in: query
      - name: order_by
        required: false
        description: Sort results by the specified field.
        schema:
          type:
          - string
          - 'null'
          enum:
          - id
          - null
        in: query
      - name: sort
        required: false
        description: Sort results in ascending or descending order. Specify `order_by` as well, including for `id`.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        in: query
      - name: cursor
        required: false
        description: Cursor for obtaining the next set of records.
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: page
        required: false
        description: Page number of results to retrieve.
        schema:
          type: integer
          default: 1
        in: query
        example: 1
      - name: per_page
        required: false
        description: Number of items to list per page.
        schema:
          type: integer
          default: 20
        in: query
        example: 20
  /api/v4/jobs/request:
    post:
      operationId: postApiV4JobsRequest
      summary: Request a job
      description: Requests a job for a runner to execute.
      tags:
      - Jobs
      responses:
        '201':
          description: Job was scheduled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesCiJobRequestResponse'
        '204':
          description: No job for Runner
        '403':
          description: Forbidden
        '409':
          description: Conflict
        '422':
          description: Runner is orphaned
        '429':
          description: Too Many Requests
        '400':
          description: Bad Request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4JobsRequestRequest'
  /api/v4/jobs/{id}:
    put:
      operationId: putApiV4JobsId
      summary: Update a job
      description: Updates the state and other attributes of a job. Used by runners while executing a job.
      tags:
      - Jobs
      responses:
        '200':
          description: Job was updated
        '202':
          description: Update accepted
        '400':
          description: Unknown parameters
        '403':
          description: Forbidden
        '409':
          description: Conflict
        '429':
          description: Too Many Requests
        '404':
          description: Not Found
      parameters:
      - name: id
        required: true
        description: ID of the job.
        schema:
          type: integer
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/putApiV4JobsIdRequest'
  /api/v4/jobs/{id}/runtime_environment_key:
    get:
      operationId: getApiV4JobsIdRuntimeEnvironmentKey
      summary: Get the runtime environment key for a job
      description: Retrieves the runtime environment key linked to a job, if the job is resuming a suspended environment.
      tags:
      - Jobs
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesCiRuntimeEnvironmentKey'
        '403':
          description: Forbidden
        '404':
          description: Not found
        '429':
          description: Too Many Requests
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the job.
        schema:
          type: integer
        in: path
      - name: token
        required: false
        description: Authentication token of the job.
        schema:
          type:
          - string
          - 'null'
        in: query
  /api/v4/jobs/{id}/trace:
    patch:
      operationId: patchApiV4JobsIdTrace
      summary: Update the trace of a job
      description: Updates the trace of a job by appending a chunk of log output. Used by runners while executing a job.
      tags:
      - Jobs
      responses:
        '202':
          description: Trace was patched
        '400':
          description: Missing Content-Range header
        '403':
          description: Forbidden
        '416':
          description: Range not satisfiable
        '429':
          description: Too Many Requests
        '404':
          description: Not Found
      parameters:
      - name: id
        required: true
        description: ID of the job.
        schema:
          type: integer
        in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/patchApiV4JobsIdTraceRequest'
  /api/v4/jobs/{id}/artifacts/authorize:
    post:
      operationId: postApiV4JobsIdArtifactsAuthorize
      summary: Authorize artifacts upload
      description: Authorizes uploading artifacts for a specified job.
      tags:
      - Jobs
      responses:
        '200':
          description: Upload allowed
        '403':
          description: Forbidden
        '405':
          description: Artifacts support not enabled
        '413':
          description: File too large
        '429':
          description: Too Many Requests
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the job.
        schema:
          type: integer
        in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4JobsIdArtifactsAuthorizeRequest'
  /api/v4/jobs/{id}/artifacts:
    post:
      operationId: postApiV4JobsIdArtifacts
      summary: Upload job artifacts
      description: Uploads artifacts for a specified job.
      tags:
      - Jobs
      responses:
        '201':
          description: Created
        '400':
          description: Bad request
        '403':
          description: Forbidden
        '405':
          description: Artifacts support not enabled
        '413':
          description: File too large
        '429':
          description: Too Many Requests
        '404':
          description: Not Found
      parameters:
      - name: id
        required: true
        description: ID of the job.
        schema:
          type: integer
        in: path
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/postApiV4JobsIdArtifactsRequest'
    get:
      operationId: getApiV4JobsIdArtifacts
      summary: Download job artifacts
      description: Downloads artifacts for a specified job.
      tags:
      - Jobs
      responses:
        '200':
          description: Download allowed
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '302':
          description: Found
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Artifact not found
        '429':
          description: Too Many Requests
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the job.
        schema:
          type: integer
        in: path
      - name: token
        required: false
        description: Authentication token of the job.
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: direct_download
        required: false
        description: If `true`, performs a direct download of artifacts from remote storage instead of proxying them.
        schema:
          type: boolean
          default: false
        in: query
      - name: download_mode
        required: false
        description: Requested download transfer mode (`proxy` or `direct`). Only honored when allowed by the object storage configuration.
        schema:
          type:
          - string
          - 'null'
          enum:
          - proxy
          - direct
          - null
        in: query
components:
  schemas:
    APIEntitiesCommit:
      type: object
      properties:
        id:
          type: string
          example: 2695effb5807a22ff3d138d593fd856244e155e7
        short_id:
          type: string
          example: 2695effb
        created_at:
          type: string
          format: date-time
          example: '2017-07-26T11:08:53.000+02:00'
        parent_ids:
          type: array
          example:
          - 2a4b78934375d7f53875269ffd4f45fd83a84ebe
          items:
            type: string
        title:
          type: string
          example: Initial commit
        message:
          type: string
          example: Initial commit
        author_name:
          type: string
          example: John Smith
        author_email:
          type: string
          example: john@example.com
        authored_date:
          type: string
          format: date-time
          example: '2012-05-28T04:42:42-07:00'
        committer_name:
          type: string
          example: Jack Smith
        committer_email:
          type: string
          example: jack@example.com
        committed_date:
          type: string
          format: date-time
          example: '2012-05-28T04:42:42-07:00'
        trailers:
          type: object
          example:
            Merged-By: Jane Doe janedoe@gitlab.com
        extended_trailers:
          type: object
          example:
            Signed-off-by:
            - John Doe <johndoe@gitlab.com>
            - Jane Doe <janedoe@gitlab.com>
        web_url:
          type: string
          example: https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746
    postApiV4JobsRequestRequest:
      type: object
      properties:
        token:
          type:
          - string
          - 'null'
          description: Runner's authentication token
        system_id:
          type:
          - string
          - 'null'
          description: Runner's system identifier
        last_update:
          type:
          - string
          - 'null'
          description: '`last_update` token of the runner queue.'
        info:
          type:
          - object
          - 'null'
          description: Runner's metadata
          properties:
            name:
              type:
              - string
              - 'null'
              description: Runner's name
            version:
              type:
              - string
              - 'null'
              description: Runner's version
            revision:
              type:
              - string
              - 'null'
              description: Runner's revision
            platform:
              type:
              - string
              - 'null'
              description: Runner's platform
            architecture:
              type:
              - string
              - 'null'
              description: Runner's architecture
            executor:
              type:
              - string
              - 'null'
              description: Runner's executor
            features:
              type:
              - object
              - 'null'
              description: Runner's features
            config:
              type:
              - object
              - 'null'
              description: Runner's config
              properties:
                gpus:
                  type:
                  - string
                  - 'null'
                  description: GPUs enabled
            labels:
              type:
              - object
              - 'null'
              description: Runner's labels
        session:
          type:
          - object
          - 'null'
          description: Session data of the runner.
          properties:
            url:
              type:
              - string
              - 'null'
              description: URL of the session.
            certificate:
              type:
              - string
              - 'null'
              description: Certificate of the session.
            authorization:
              type:
              - string
              - 'null'
              description: Authorization of the session.
      required:
      - token
    APIEntitiesCiJobBasicWithProject:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        status:
          type: string
          example: waiting_for_resource
        stage:
          type: string
          example: deploy
        name:
          type: string
          example: deploy_to_production
        ref:
          type: string
          example: main
        tag:
          type: boolean
        coverage:
          type: number
          format: float
          example: 98.29
        allow_failure:
          type: boolean
        created_at:
          type: string
          format: date-time
          example: '2015-12-24T15:51:21.880Z'
        started_at:
          type: string
          format: date-time
          example: '2015-12-24T17:54:30.733Z'
        finished_at:
          type: string
          format: date-time
          example: '2015-12-24T17:54:31.198Z'
        erased_at:
          type: string
          format: date-time
          example: '2015-12-24T18:00:29.728Z'
        duration:
          type: number
          description: Time spent running
          format: float
          example: 0.465
        queued_duration:
          type: number
          description: Time spent enqueued
          format: float
          example: 0.123
        user:
          $ref: '#/components/schemas/APIEntitiesUser'
        commit:
          $ref: '#/components/schemas/APIEntitiesCommit'
        pipeline:
          $ref: '#/components/schemas/APIEntitiesCiPipelineBasic'
        failure_reason:
          type: string
          example: script_failure
        web_url:
          type: string
          example: https://example.com/foo/bar/-/jobs/1
        project:
          $ref: '#/components/schemas/APIEntitiesProjectIdentity'
    APIEntitiesCiJobRequestArtifacts:
      type: object
      properties:
        name:
          type: string
        untracked:
          type: string
        paths:
          type: string
        exclude:
          type: string
        when:
          type: string
        expire_in:
          type: string
        artifact_type:
          type: string
        artifact_format:
          type: string
    APIEntitiesProjectIdentity:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        description:
          type: string
          example: desc
        name:
          type: string
          example: project1
        name_with_namespace:
          type: string
          example: John Doe / project1
        path:
          type: string
          example: project1
        path_with_namespace:
          type: string
          example: namespace1/project1
        created_at:
          type: string
          format: date-time
          example: '2020-05-07T04:27:17.016Z'
    APIEntitiesCiJobRequestResponse:
      type: object
      properties:
        id:
          type: string
        token:
          type: string
        allow_git_fetch:
          type: string
        job_info:
          $ref: '#/components/schemas/APIEntitiesCiJobRequestJobInfo'
        git_info:
          $ref: '#/components/schemas/APIEntitiesCiJobRequestGitInfo'
        runner_info:
          $ref: '#/components/schemas/APIEntitiesCiJobRequestRunnerInfo'
        inputs:
          type: string
        variables:
          type: string
        steps:
          $ref: '#/components/schemas/APIEntitiesCiJobRequestStep'
        hooks:
          $ref: '#/components/schemas/APIEntitiesCiJobRequestHook'
        image:
          $ref: '#/components/schemas/APIEntitiesCiJobRequestImage'
        services:
          $ref: '#/components/schemas/APIEntitiesCiJobRequestService'
        artifacts:
          $ref: '#/components/schemas/APIEntitiesCiJobRequestArtifacts'
        cache:
          $ref: '#/components/schemas/APIEntitiesCiJobRequestCache'
        credentials:
          $ref: '#/components/schemas/APIEntitiesCiJobRequestCredentials'
        features:
          type: string
        dependencies:
          type: string
        run:
          type: string
        suspend_options:
          type: string
        secrets:
          type: string
        policy_options:
          type: string
    APIEntitiesCiRuntimeEnvironmentKey:
      type: object
      properties:
        runtime_environment_key:
          type: string
          example: 42/s_machineid/data
    APIEntitiesCustomAttribute:
      type: object
      properties:
        key:
          type: string
          example: foo
        value:
          type: string
          example: bar
    putApiV4JobsIdRequest:
      type: object
      properties:
        token:
          type:
          - string
          - 'null'
          description: Authentication token of the job.
        state:
          type:
          - string
          - 'null'
          description: 'Status of the job: `running`, `success`, or `failed`.'
        checksum:
          type:
          - string
          - 'null'
          description: CRC32 checksum of the job trace.
        failure_reason:
          type:
          - string
          - 'null'
          description: Failure reason of the job.
        output:
          type:
          - object
          - 'null'
          description: Build log state.
          properties:
            checksum:
              type:
              - string
              - 'null'
              description: CRC32 checksum of the job trace.
            bytesize:
              type:
              - integer
              - 'null'
              description: Size of the job's trace output, in bytes.
        exit_code:
          type:
          - integer
          - 'null'
          description: Exit code of the job.
        runtime_environment_key:
          type:
          - string
          - 'null'
          description: Runtime environment key emitted by the runner on job suspension
          maxLength: 512
      required:
      - token
    APIEntitiesCiJobRequestJobInfo:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        stage:
          type: string
        pipeline_id:
          type: string
        project_id:
          type: string
        project_name:
          type: string
        project_full_path:
          type: string
        namespace_id:
          type: string
        root_namespace_id:
          type: string
        organization_id:
          type: string
        instance_id:
          type: string
        instance_uuid:
          type: string
        user_id:
          type: string
        scoped_user_id:
          type: string
        time_in_queue_seconds:
          type: string
        project_jobs_running_on_instance_runners_count:
          type: string
        queue_size:
          type: string
        queue_depth:
          type: string
    APIEntitiesCiJobRequestCredentials:
      type: object
      properties:
        type:
          type: string
        url:
          type: string
        username:
          type: string
        password:
          type: string
    APIEntitiesCiJobRequestService:
      type: object
      properties:
        name:
          type: string
        entrypoint:
          type: string
        ports:
          $ref: '#/components/schemas/APIEntitiesCiJobRequestPort'
        executor_opts:
          type: string
        pull_policy:
          type: string
        alias:
          type: string
        command:
          type: string
        variables:
          type: string
    patchApiV4JobsIdTraceRequest:
      type: object
      properties:
        token:
          type:
          - string
          - 'null'
          description: Authentication token of the job.
        debug_trace:
          type:
          - boolean
          - 'null'
          description: If `true`, enables debug tracing for the job.
    postApiV4JobsIdArtifactsRequest:
      type: object
      properties:
        file:
          type:
          - string
          - 'null'
          format: binary
          description: The artifact file to store (generated by Multipart middleware)
        token:
          type:
          - string
          - 'null'
          description: Authentication token of the job.
        expire_in:
          type:
          - string
          - 'null'
          description: Specify when artifact should expire
        artifact_type:
          type: string
          enum:
          - archive
          - metadata
          - trace
          - junit
          - sast
          - dependency_scanning
          - container_scanning
          - dast
          - codequality
          - license_scanning
          - performance
          - metrics
          - metrics_referee
          - network_referee
          - lsif
          - dotenv
          - cobertura
          - terraform
          - accessibility
          - cluster_applications
          - secret_detection
          - requirements
          - coverage_fuzzing
          - browser_performance
          - load_performance
          - api_fuzzing
          - cluster_image_scanning
          - cyclonedx
          - requirements_v2
          - annotations
          - repository_xray
          - jacoco
          - sarif
          description: Type of artifact.
          default: archive
        artifact_format:
          type: string
          enum:
          - raw
          - zip
          - gzip
          description: The format of artifact
          default: zip
        metadata:
          type:
          - string
          - 'null'
          format: binary
          description: The artifact metadata to store (generated by Multipart middleware)
        accessibility:
          type:
          - string
          - 'null'
          description: Specify accessibility level of artifact private/public
      required:
      - file
    APIEntitiesUser:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        username:
          type: string
          example: admin
        public_email:
          type: string
          example: john@example.com
        name:
          type: string
          example: Administrator
        state:
          type: string
          example: active
        locked:
          type: boolean
        avatar_url:
          type: string
          example: https://gravatar.com/avatar/1
        avatar_path:
          type: string
          example: /user/avatar/28/The-Big-Lebowski-400-400.png
        custom_attributes:
          type: array
          items:
            $ref: '#/components/schemas/APIEntitiesCustomAttribute'
        web_url:
          type: string
          example: https://gitlab.example.com/root
        created_at:
          type: string
        bio:
          type: string
        location:
          type: string
        linkedin:
          type: string
        twitter:
          type: string
        discord:
          type: string
        website_url:
          type: string
        github:
          type: string
        job_title:
          type: string
        pronouns:
          type: string
        organization:
          type: string
        bot:
          type: boolean
        work_information:
          type: string
        followers:
          type: string
        following:
          type: string
        is_followed:
          type: string
        local_time:
          type: string
    postApiV4JobsIdArtifactsAuthorizeRequest:
      type: object
      properties:
        token:
          type:
          - string
          - 'null'
          description: Authentication token of the job.
        filesize:
          type:
          - integer
          - 'null'
          description: Size of the artifact file.
        artifact_type:
          type: string
          enum:
          - archive
          - metadata
          - trace
          - junit
          - sast
          - dependency_scanning
          - container_scanning
          - dast
          - codequality
          - license_scanning
          - performance
          - metrics
          - metrics_referee
          - network_referee
          - lsif
          - dotenv
          - cobertura
          - terraform
          - accessibility
          - cluster_applications
          - secret_detection
          - requirements
          - coverage_fuzzing
          - browser_performance
          - load_performance
          - api_fuzzing
          - cluster_image_scanning
          - cyclonedx
          - requirements_v2
          - annotations
          - repository_xray
          - jacoco
          - sarif
          description: Type of artifact.
          default: archive
    APIEntitiesCiJobRequestStep:
      type: object
      properties:
        name:
          type: string
        script:
          type: string
        timeout:
          type: string
        when:
          type: string
        allow_failure:
          type: string
    APIEntitiesCiJobRequestHook:
      type: object
      properties:
        name:
          type: string
        script:
          type: string
    APIEntitiesCiJobRequestCache:
      type: object
      properties:
        key:
          type: string
        untracked:
          type: string
        paths:
          type: string
        policy:
          type: string
        when:
          type: string
        fallback_keys:
          type: string
    APIEntitiesCiJobRequestImage:
      type: object
      properties:
        name:
          type: string
        entrypoint:
          type: string
        ports:
          $ref: '#/components/schemas/APIEntitiesCiJobRequestPort'
        executor_opts:
          type: string
        pull_policy:
          type: string
    APIEntitiesCiJobRequestPort:
      type: object
      properties:
        number:
          type: string
        protocol:
          type: string
        name:
          type: string
    APIEntitiesCiJobRequestRunnerInfo:
      type: object
      properties:
        uuid:
          type: string
        timeout:
          type: string
        runner_session_url:
          type: string
    APIEntitiesCiJobRequestGitInfo:
      type: object
      properties:
        repo_url:
          type: string
        ref:
          type: string
        sha:
          type: string
        before_sha:
          type: string
        ref_type:
          type: string
        refspecs:
          type: string
        depth:
          type: string
        repo_object_format:
          type: string
        protected:
          type: string
    APIEntitiesCiPipelineBasic:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        iid:
          type: integer
          example: 2
        project_id:
          type: integer
          format: int64
          example: 3
        sha:
          type: string
          example: 0ec9e58fdfca6cdd6652c083c9edb53abc0bad52
        ref:
          type: string
          example: feature-branch
        status:
          type: string
          example: success
        source:
          type: string
          example: push
        created_at:
          type: string
          format: date-time
          example: '2022-10-21T16:49:48.000+02:00'
        updated_at:
          type: string
          format: date-time
          example: '2022-10-21T16:49:48.000+02:00'
        web_url:
          type: string
          example: https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61
  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