Documentation
Documentation
https://docs.gitlab.com/api/
APIReference
https://docs.gitlab.com/api/api_resources/
Authentication
https://docs.gitlab.com/api/rest/authentication/
OpenAPI Specification
swagger: '2.0'
info:
title: GitLab access_requests runners API
version: v4
description: Operations related to access requests
host: gitlab.com
produces:
- application/json
tags:
- name: runners
description: Operations about runners
paths:
/api/v4/groups/{id}/runners:
get:
summary: List group's runners
description: List all runners available in the group as well as its ancestor groups, including any allowed shared runners.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID of a group
type: string
required: true
- in: query
name: type
description: The type of runners to return
type: string
enum:
- instance_type
- group_type
- project_type
required: false
- in: query
name: paused
description: Whether to include only runners that are accepting or ignoring new jobs
type: boolean
required: false
- in: query
name: status
description: The status of runners to return
type: string
enum:
- active
- paused
- online
- offline
- never_contacted
- stale
required: false
- in: query
name: tag_list
description: A list of runner tags
type: array
items:
type: string
required: false
example: '[''macos'', ''shell'']'
- in: query
name: version_prefix
description: The version prefix of runners to return
type: string
required: false
example: '''15.1.'' or ''16.'''
- in: query
name: page
description: Current page number
type: integer
format: int32
default: 1
required: false
example: 1
- in: query
name: per_page
description: Number of items per page
type: integer
format: int32
default: 20
required: false
example: 20
responses:
'200':
description: Get runners available for group
schema:
$ref: '#/definitions/API_Entities_Ci_Runner'
'400':
description: Scope contains invalid value
'403':
description: Forbidden
tags:
- runners
operationId: getApiV4GroupsIdRunners
/api/v4/groups/{id}/runners/reset_registration_token:
post:
summary: Reset the runner registration token for a group
description: Reset runner registration token
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID of a group
type: string
required: true
responses:
'201':
description: Reset runner registration token
schema:
$ref: '#/definitions/API_Entities_Ci_ResetTokenResult'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Group Not Found
tags:
- runners
operationId: postApiV4GroupsIdRunnersResetRegistrationToken
/api/v4/projects/{id}/runners:
get:
summary: List project's runners
description: List all runners available in the project, including from ancestor groups and any allowed shared runners.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project owned by the authenticated user
type: string
required: true
- in: query
name: scope
description: 'Deprecated: Use `type` or `status` instead. The scope of runners to return'
type: string
enum:
- specific
- shared
- instance_type
- group_type
- project_type
- active
- paused
- online
- offline
- never_contacted
- stale
required: false
- in: query
name: type
description: The type of runners to return
type: string
enum:
- instance_type
- group_type
- project_type
required: false
- in: query
name: paused
description: Whether to include only runners that are accepting or ignoring new jobs
type: boolean
required: false
- in: query
name: status
description: The status of runners to return
type: string
enum:
- active
- paused
- online
- offline
- never_contacted
- stale
required: false
- in: query
name: tag_list
description: A list of runner tags
type: array
items:
type: string
required: false
example: '[''macos'', ''shell'']'
- in: query
name: version_prefix
description: The version prefix of runners to return
type: string
required: false
example: '''15.1.'' or ''16.'''
- in: query
name: page
description: Current page number
type: integer
format: int32
default: 1
required: false
example: 1
- in: query
name: per_page
description: Number of items per page
type: integer
format: int32
default: 20
required: false
example: 20
responses:
'200':
description: Get runners available for project
schema:
$ref: '#/definitions/API_Entities_Ci_Runner'
'400':
description: Scope contains invalid value
'403':
description: No access granted
tags:
- runners
operationId: getApiV4ProjectsIdRunners
post:
summary: Assign a runner to project
description: Assign an available project runner to the project.
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project owned by the authenticated user
type: string
required: true
- name: postApiV4ProjectsIdRunners
in: body
required: true
schema:
$ref: '#/definitions/postApiV4ProjectsIdRunners'
responses:
'201':
description: Assign a runner to project
schema:
$ref: '#/definitions/API_Entities_Ci_Runner'
'400':
description: Bad Request
'403':
description: No access granted
'404':
description: Runner not found
tags:
- runners
operationId: postApiV4ProjectsIdRunners
/api/v4/projects/{id}/runners/{runner_id}:
delete:
summary: Unassign a project runner from the project
description: It is not possible to unassign a runner from the owner project. If so, an error is returned. Use the call to delete a runner instead.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project owned by the authenticated user
type: string
required: true
- in: path
name: runner_id
description: The ID of a runner
type: integer
format: int32
required: true
responses:
'400':
description: Bad Request
'204':
description: Unassign a runner from project
schema:
$ref: '#/definitions/API_Entities_Ci_Runner'
'403':
description: You cannot unassign a runner from the owner project. Delete the runner instead
'404':
description: Runner not found
'412':
description: Precondition Failed
tags:
- runners
operationId: deleteApiV4ProjectsIdRunnersRunnerId
/api/v4/projects/{id}/runners/reset_registration_token:
post:
summary: Reset the runner registration token for a project
description: Reset runner registration token
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID of a project
type: string
required: true
responses:
'201':
description: Reset runner registration token
schema:
$ref: '#/definitions/API_Entities_Ci_ResetTokenResult'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Project Not Found
tags:
- runners
operationId: postApiV4ProjectsIdRunnersResetRegistrationToken
/api/v4/runners:
get:
summary: List available runners
description: Get runners available for user
produces:
- application/json
parameters:
- in: query
name: scope
description: 'Deprecated: Use `type` or `status` instead. The scope of runners to return'
type: string
enum:
- specific
- shared
- instance_type
- group_type
- project_type
- active
- paused
- online
- offline
- never_contacted
- stale
required: false
- in: query
name: type
description: The type of runners to return
type: string
enum:
- instance_type
- group_type
- project_type
required: false
- in: query
name: paused
description: Whether to include only runners that are accepting or ignoring new jobs
type: boolean
required: false
- in: query
name: status
description: The status of runners to return
type: string
enum:
- active
- paused
- online
- offline
- never_contacted
- stale
required: false
- in: query
name: tag_list
description: A list of runner tags
type: array
items:
type: string
required: false
example: '[''macos'', ''shell'']'
- in: query
name: version_prefix
description: The version prefix of runners to return
type: string
required: false
example: '''15.1.'' or ''16.'''
- in: query
name: page
description: Current page number
type: integer
format: int32
default: 1
required: false
example: 1
- in: query
name: per_page
description: Number of items per page
type: integer
format: int32
default: 20
required: false
example: 20
responses:
'200':
description: Get runners available for user
schema:
$ref: '#/definitions/API_Entities_Ci_Runner'
'400':
description: Scope contains invalid value
'401':
description: Unauthorized
tags:
- runners
operationId: getApiV4Runners
/api/v4/runners/all:
get:
summary: List all runners
description: Get a list of all runners in the GitLab instance (shared and project). Access is restricted to users with either administrator access or auditor access.
produces:
- application/json
parameters:
- in: query
name: scope
description: 'Deprecated: Use `type` or `status` instead. The scope of runners to return'
type: string
enum:
- specific
- shared
- instance_type
- group_type
- project_type
- active
- paused
- online
- offline
- never_contacted
- stale
required: false
- in: query
name: type
description: The type of runners to return
type: string
enum:
- instance_type
- group_type
- project_type
required: false
- in: query
name: paused
description: Whether to include only runners that are accepting or ignoring new jobs
type: boolean
required: false
- in: query
name: status
description: The status of runners to return
type: string
enum:
- active
- paused
- online
- offline
- never_contacted
- stale
required: false
- in: query
name: tag_list
description: A list of runner tags
type: array
items:
type: string
required: false
example: '[''macos'', ''shell'']'
- in: query
name: version_prefix
description: The version prefix of runners to return
type: string
required: false
example: '''15.1.'' or ''16.'''
- in: query
name: page
description: Current page number
type: integer
format: int32
default: 1
required: false
example: 1
- in: query
name: per_page
description: Number of items per page
type: integer
format: int32
default: 20
required: false
example: 20
responses:
'200':
description: Get all runners - shared and project
schema:
$ref: '#/definitions/API_Entities_Ci_Runner'
'400':
description: Scope contains invalid value
'401':
description: Unauthorized
tags:
- runners
operationId: getApiV4RunnersAll
/api/v4/runners/{id}:
get:
summary: Get runner's details
description: At least the Maintainer role is required to get runner details at the project and group level. Instance-level runner details via this endpoint are available to all signed in users.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID of a runner
type: integer
format: int32
required: true
- in: query
name: include_projects
description: Include projects in the response. Set to false to improve performance for runners with many projects.
type: boolean
default: true
required: false
responses:
'200':
description: Get runner's details
schema:
$ref: '#/definitions/API_Entities_Ci_RunnerDetails'
'401':
description: Unauthorized
'403':
description: No access granted
'404':
description: Runner not found
tags:
- runners
operationId: getApiV4RunnersId
put:
summary: Update details of a runner
description: Update runner's details
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID of a runner
type: integer
format: int32
required: true
- name: putApiV4RunnersId
in: body
required: true
schema:
$ref: '#/definitions/putApiV4RunnersId'
responses:
'200':
description: Update runner's details
schema:
$ref: '#/definitions/API_Entities_Ci_RunnerDetails'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: No access granted
'404':
description: Runner not found
tags:
- runners
operationId: putApiV4RunnersId
delete:
summary: Delete a runner
description: Remove a runner
produces:
- application/json
parameters:
- in: path
name: id
description: The ID of a runner
type: integer
format: int32
required: true
responses:
'401':
description: Unauthorized
'204':
description: Remove a runner
schema:
$ref: '#/definitions/API_Entities_Ci_Runner'
'403':
description: No access granted
'404':
description: Runner not found
'412':
description: Precondition Failed
tags:
- runners
operationId: deleteApiV4RunnersId
/api/v4/runners/{id}/managers:
get:
description: Get a list of all runner's managers
produces:
- application/json
parameters:
- in: path
name: id
description: The ID of a runner
type: integer
format: int32
required: true
responses:
'200':
description: Get a list of all runner's managers
schema:
$ref: '#/definitions/API_Entities_Ci_RunnerManager'
'403':
description: Forbidden
tags:
- runners
operationId: getApiV4RunnersIdManagers
/api/v4/runners/{id}/projects:
get:
summary: List runner's projects
description: Get a paginated list of all projects associated with the specified runner. Access is restricted based on user permissions.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID of a runner
type: integer
format: int32
required: true
- in: query
name: page
description: Current page number
type: integer
format: int32
default: 1
required: false
example: 1
- in: query
name: per_page
description: Number of items per page
type: integer
format: int32
default: 20
required: false
example: 20
responses:
'200':
description: Get projects associated with a runner
schema:
$ref: '#/definitions/API_Entities_BasicProjectDetails'
'401':
description: Unauthorized
'403':
description: No access granted
'404':
description: Runner not found
tags:
- runners
operationId: getApiV4RunnersIdProjects
/api/v4/runners/{id}/jobs:
get:
summary: List runner's jobs
description: List jobs that are being processed or were processed by the specified runner. The list of jobs is limited to projects where the user has at least the Reporter role.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID of a runner
type: integer
format: int32
required: true
- in: query
name: system_id
description: System ID associated with the runner manager
type: string
required: false
- in: query
name: status
description: Status of the job
type: string
enum:
- created
- waiting_for_resource
- preparing
- waiting_for_callback
- pending
- running
- success
- failed
- canceling
- canceled
- skipped
- manual
- scheduled
required: false
- in: query
name: order_by
description: Order by `id`
type: string
enum:
- id
required: false
- in: query
name: sort
description: Sort by `asc` or `desc` order. Specify `order_by` as well, including for `id`
type: string
default: desc
enum:
- asc
- desc
required: false
- in: query
name: cursor
description: Cursor for obtaining the next set of records
type: string
required: false
- in: query
name: page
description: Current page number
type: integer
format: int32
default: 1
required: false
example: 1
- in: query
name: per_page
description: Number of items per page
type: integer
format: int32
default: 20
required: false
example: 20
responses:
'200':
description: List jobs running on a runner
schema:
$ref: '#/definitions/API_Entities_Ci_JobBasicWithProject'
'401':
description: Unauthorized
'403':
description: No access granted
'404':
description: Runner not found
tags:
- runners
operationId: getApiV4RunnersIdJobs
/api/v4/runners/{id}/reset_authentication_token:
post:
summary: Reset runner's authentication token
description: Reset runner authentication token
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID of the runner
type: integer
format: int32
required: true
responses:
'201':
description: Reset runner authentication token
schema:
$ref: '#/definitions/API_Entities_Ci_ResetTokenResult'
'403':
description: No access granted
'404':
description: Runner not found
'422':
description: Unprocessable Entity
tags:
- runners
operationId: postApiV4RunnersIdResetAuthenticationToken
/api/v4/runners/reset_registration_token:
post:
summary: Reset instance's runner registration token
description: Reset runner registration token
produces:
- application/json
consumes:
- application/json
responses:
'201':
description: Reset runner registration token
schema:
$ref: '#/definitions/API_Entities_Ci_ResetTokenResult'
'403':
description: Forbidden
tags:
- runners
operationId: postApiV4RunnersResetRegistrationToken
/api/v4/user/runners:
post:
summary: Create a runner owned by currently authenticated user
description: Create a new runner
produces:
- application/json
consumes:
- application/json
parameters:
- name: postApiV4UserRunners
in: body
required: true
schema:
$ref: '#/definitions/postApiV4UserRunners'
responses:
'201':
description: Create a runner owned by currently authenticated user
schema:
$ref: '#/definitions/API_Entities_Ci_RunnerRegistrationDetails'
'400':
description: Bad Request
'403':
description: Forbidden
tags:
- runners
operationId: postApiV4UserRunners
definitions:
API_Entities_CustomAttribute:
type: object
properties:
key:
type: string
example: foo
value:
type: string
example: bar
required:
- key
- value
description: API_Entities_CustomAttribute model
API_Entities_Ci_Runner:
type: object
properties:
id:
type: integer
format: int32
example: 8
description:
type: string
example: test-1-20150125
ip_address:
type: string
example: 127.0.0.1
active:
type: boolean
example: true
paused:
type: boolean
example: false
is_shared:
type: boolean
example: true
runner_type:
type: string
enum:
- instance_type
- group_type
- project_type
example: instance_type
name:
type: string
example: test
online:
type: boolean
example: true
created_by:
$ref: '#/definitions/API_Entities_UserBasic'
created_at:
type: string
format: date-time
example: '2025-05-03T00:00:00.000Z'
status:
type: string
example: online
job_execution_status:
type: string
enum:
- active
- idle
example: idle
required:
- id
- description
- ip_address
- active
- paused
- is_shared
- runner_type
- name
- online
- created_at
- status
- job_execution_status
description: API_Entities_Ci_Runner model
API_Entities_Ci_RunnerManager:
type: object
properties:
id:
type: integer
format: int32
example: 8
system_id:
type: string
example: runner-1
version:
type: string
example: 16.11.0
revision:
type: string
example: 91a27b2a
platform:
type: string
example: linux
architecture:
type: string
example: amd64
created_at:
type: string
example: '2023-10-24T01:27:06.549Z'
contacted_at:
type: string
example: '2023-10-24T01:27:06.549Z'
ip_address:
type: string
example: 127.0.0.1
status:
type: string
example: online
job_execution_status:
type: string
enum:
- active
- idle
example: idle
required:
- id
- system_id
- version
- revision
- platform
- architecture
- created_at
- contacted_at
- ip_address
- status
- job_execution_status
description: API_Entities_Ci_RunnerManager model
API_Entities_UserBasic:
type: object
properties:
id:
type: integer
format: int32
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: '#/definitions/API_Entities_CustomAttribute'
web_url:
type: string
example: https://gitlab.example.com/root
required:
- id
- username
- public_email
- name
- state
- locked
- avatar_url
- web_url
description: API_Entities_UserBasic model
API_Entities_ProjectIdentity:
type: object
properties:
id:
type: integer
format: int32
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'
required:
- id
- description
- name
- name_with_namespace
- path
- path_with_namespace
- created_at
API_Entities_User:
type: object
properties:
id:
type: integer
format: int32
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: '#/definitions/API_Entities_CustomAttribute'
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
required:
- id
- username
- public_email
- name
- state
- locked
- avatar_url
- web_url
- bio
- location
- linkedin
- twitter
- discord
- website_url
- github
- job_title
- pronouns
- organization
- bot
- work_information
- local_time
API_Entities_Ci_JobBasicWithProject:
type: object
properties:
id:
type: integer
format: int32
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
format: float
example: 0.465
description: Time spent running
queued_duration:
type: number
format: float
example: 0.123
description: Time spent enqueued
user:
$ref: '#/definitions/API_Entities_User'
commit:
$ref: '#/definitions/API_Entities_Commit'
pipeline:
$ref: '#/definitions/API_Entities_Ci_PipelineBasic'
failure_reason:
type: string
example: script_failure
web_url:
type: string
example: https://example.com/foo/bar/-/jobs/1
project:
$ref: '#/definitions/API_Entities_ProjectIdentity'
required:
- id
- status
- stage
- name
- ref
- tag
- coverage
- allow_failure
- created_at
- started_at
- finished_at
- erased_at
- duration
- queued_duration
- user
- commit
- pipeline
- web_url
- project
description: API_Entities_Ci_JobBasicWithProject model
putApiV4RunnersId:
type: object
properties:
description:
type: string
description: The description of the runner
active:
type: boolean
description: 'Deprecated: Use `paused` instead. Flag indicating whether the runner is allowed to receive jobs'
paused:
type: boolean
description: Specifies if the runner should ignore new jobs
tag_list:
type: array
description: The list of tags for a runner
example: '[''macos'', ''shell'']'
items:
type: string
run_untagged:
type: boolean
description: Specifies if the runner can execute untagged jobs
locked:
type: boolean
description: Specifies if the runner is locked
access_level:
type: string
description: The access level of the runner
enum:
- not_protected
- ref_protected
maximum_timeout:
type: integer
format: int32
description: Maximum timeout that limits the amount of time (in seconds) that runners can run jobs
maintenance_note:
type: string
description: Free-form maintenance notes for the runner (1024 characters)
description: Update runner's details
API_Entities_Ci_PipelineBasic:
type: object
properties:
id:
type: integer
format: int32
example: 1
iid:
type: integer
format: int32
example: 2
project_id:
type: integer
format: int32
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: s
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gitlab-ci/refs/heads/main/openapi/gitlab-ci-runners-api-openapi.yml