Use this API to manage the runners already registered to an instance, group, or project.

To create a runner, use the POST /user/runners endpoint instead.

List all runners in a group

GET /api/v4/groups/{id}/runners

Lists all runners available in a specified group and any ancestor groups, including any allowed instance runners.

Parameters

NameTypeDescription
id
Path, required
StringThe ID of a group
type
Query
StringThe type of runners to return
Allowed values: instance_type, group_type, project_type
paused
Query
BooleanWhether to include only runners that are accepting or ignoring new jobs
status
Query
StringThe status of runners to return
Allowed values: active, paused, online, offline, never_contacted, stale
tag_list
Query
Array of stringsA list of runner tags
Example: ["macos","shell"]
version_prefix
Query
StringThe version prefix of runners to return
Pattern: (?<=^|\n(?!$))[\d+.]+
Example: 15.1.
page
Query
IntegerCurrent page number
Default: 1
Example: 1
per_page
Query
IntegerNumber of items per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKAPIEntitiesCiRunner
400Scope contains invalid value—
403Forbidden—
404Not Found—

Reset runner registration token

POST /api/v4/groups/{id}/runners/reset_registration_token

FE version

Parameters

NameTypeDescription
id
Path, required
StringThe ID of a group

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesCiResetTokenResult
400Bad Request—
401Unauthorized—
403Forbidden—
404Group Not Found—

List all runners for a project

GET /api/v4/projects/{id}/runners

List all runners available in the project, including from ancestor groups and any allowed shared runners.

Parameters

NameTypeDescription
id
Path, required
String or integerThe ID or URL-encoded path of the project owned by the authenticated user
scope
Query
StringDeprecated: Use type or status instead. The scope of runners to return
Allowed values: specific, shared, instance_type, group_type, project_type, active, paused, online, offline, never_contacted, stale
type
Query
StringThe type of runners to return
Allowed values: instance_type, group_type, project_type
paused
Query
BooleanWhether to include only runners that are accepting or ignoring new jobs
status
Query
StringThe status of runners to return
Allowed values: active, paused, online, offline, never_contacted, stale
tag_list
Query
Array of stringsA list of runner tags
Example: ["macos","shell"]
version_prefix
Query
StringThe version prefix of runners to return
Pattern: (?<=^|\n(?!$))[\d+.]+
Example: 15.1.
page
Query
IntegerCurrent page number
Default: 1
Example: 1
per_page
Query
IntegerNumber of items per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKAPIEntitiesCiRunner
400Scope contains invalid value—
403No access granted—
404Not Found—

Assign a runner to a project

POST /api/v4/projects/{id}/runners

Assigns an available project runner to a project.

Parameters

NameTypeDescription
id
Path, required
String or integerThe ID or URL-encoded path of the project owned by the authenticated user

Request body (application/json)

PropertyTypeDescription
runner_id
Required
IntegerThe ID of a runner

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesCiRunner
400Bad Request—
403Runner is locked—
404Runner not found—

Reset runner registration token

POST /api/v4/projects/{id}/runners/reset_registration_token

FE version

Parameters

NameTypeDescription
id
Path, required
StringThe ID of a project

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesCiResetTokenResult
400Bad Request—
401Unauthorized—
403Forbidden—
404Project Not Found—

Unassign a runner from a project

DELETE /api/v4/projects/{id}/runners/{runner_id}

Unassigns a specified project runner from a project. You cannot unassign a runner from the owner project. Use the delete a runner operation instead.

Parameters

NameTypeDescription
id
Path, required
String or integerThe ID or URL-encoded path of the project owned by the authenticated user
runner_id
Path, required
IntegerThe ID of a runner

Responses

CodeDescriptionSchema
200OKAPIEntitiesCiRunner
400Bad Request—
403You cannot unassign a runner from the owner project. Delete the runner instead—
404Runner not found—
412Precondition Failed—

List all available runners

GET /api/v4/runners

Lists all runners available to the user. For group runners, you must have the Owner role in the owner namespace.

Parameters

NameTypeDescription
scope
Query
StringDeprecated: Use type or status instead. The scope of runners to return
Allowed values: specific, shared, instance_type, group_type, project_type, active, paused, online, offline, never_contacted, stale
type
Query
StringThe type of runners to return
Allowed values: instance_type, group_type, project_type
paused
Query
BooleanWhether to include only runners that are accepting or ignoring new jobs
status
Query
StringThe status of runners to return
Allowed values: active, paused, online, offline, never_contacted, stale
tag_list
Query
Array of stringsA list of runner tags
Example: ["macos","shell"]
version_prefix
Query
StringThe version prefix of runners to return
Pattern: (?<=^|\n(?!$))[\d+.]+
Example: 15.1.
page
Query
IntegerCurrent page number
Default: 1
Example: 1
per_page
Query
IntegerNumber of items per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKAPIEntitiesCiRunner
400Scope contains invalid value—
401Unauthorized—

List all runners

GET /api/v4/runners/all

Lists all runners in the GitLab instance (project and shared). You must have either administrator access or auditor access.

Parameters

NameTypeDescription
scope
Query
StringDeprecated: Use type or status instead. The scope of runners to return
Allowed values: specific, shared, instance_type, group_type, project_type, active, paused, online, offline, never_contacted, stale
type
Query
StringThe type of runners to return
Allowed values: instance_type, group_type, project_type
paused
Query
BooleanWhether to include only runners that are accepting or ignoring new jobs
status
Query
StringThe status of runners to return
Allowed values: active, paused, online, offline, never_contacted, stale
tag_list
Query
Array of stringsA list of runner tags
Example: ["macos","shell"]
version_prefix
Query
StringThe version prefix of runners to return
Pattern: (?<=^|\n(?!$))[\d+.]+
Example: 15.1.
page
Query
IntegerCurrent page number
Default: 1
Example: 1
per_page
Query
IntegerNumber of items per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKAPIEntitiesCiRunner
400Scope contains invalid value—
401Unauthorized—

Reset the runner registration token for the instance

POST /api/v4/runners/reset_registration_token

Resets the runner registration token for the GitLab instance.

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesCiResetTokenResult
400Bad Request—
403Forbidden—

Retrieve details on a runner

GET /api/v4/runners/{id}

Retrieves details of a runner. Instance runner details are available to all authenticated users through this endpoint. For groups and projects, you must have the Maintainer or Owner role for the associated project or group.

Parameters

NameTypeDescription
id
Path, required
IntegerThe ID of a runner
include_projects
Query
BooleanInclude projects in the response. Set to false to improve performance for runners with many projects
Default: true

Responses

CodeDescriptionSchema
200OKAPIEntitiesCiRunnerDetails
400Bad Request—
401Unauthorized—
403No access granted—
404Runner not found—

Update a runner

PUT /api/v4/runners/{id}

Updates a specified runner.

Parameters

NameTypeDescription
id
Path, required
IntegerThe ID of a runner

Request body (application/json)

PropertyTypeDescription
access_levelStringThe access level of the runner
Allowed values: not_protected, ref_protected
activeBooleanDeprecated: Use paused instead. Flag indicating whether the runner is allowed to receive jobs. Mutually exclusive with paused
descriptionStringThe description of the runner
lockedBooleanSpecifies if the runner is locked
maintenance_noteStringFree-form maintenance notes for the runner (1024 characters)
maximum_timeoutIntegerMaximum timeout that limits the amount of time (in seconds) that runners can run jobs
pausedBooleanSpecifies if the runner should ignore new jobs. Mutually exclusive with active
run_untaggedBooleanSpecifies if the runner can execute untagged jobs
tag_listArray of stringsThe list of tags for a runner

Responses

CodeDescriptionSchema
200OKAPIEntitiesCiRunnerDetails
400Bad Request—
401Unauthorized—
403No access granted—
404Runner not found—

Delete a runner

DELETE /api/v4/runners/{id}

Deletes a specified runner.

Parameters

NameTypeDescription
id
Path, required
IntegerThe ID of a runner

Responses

CodeDescriptionSchema
200OKAPIEntitiesCiRunner
400Bad Request—
401Unauthorized—
403Runner associated with more than one project—
404Runner not found—
412Precondition Failed—

List all jobs processed by a runner

GET /api/v4/runners/{id}/jobs

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.

Parameters

NameTypeDescription
id
Path, required
IntegerThe ID of a runner
system_id
Query
StringSystem ID associated with the runner manager
status
Query
StringStatus of the job
Allowed values: created, waiting_for_resource, preparing, waiting_for_callback, pending, running, success, failed, canceling, canceled, skipped, manual, scheduled
order_by
Query
StringOrder by id
Allowed values: id
sort
Query
StringSort by asc or desc order. Specify order_by as well, including for id
Allowed values: asc, desc
Default: desc
cursor
Query
StringCursor for obtaining the next set of records
page
Query
IntegerCurrent page number
Default: 1
Example: 1
per_page
Query
IntegerNumber of items per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKAPIEntitiesCiJobBasicWithProject
400Bad Request—
401Unauthorized—
403No access granted—
404Runner not found—

List all managers for a runner

GET /api/v4/runners/{id}/managers

List all managers for a specified runner.

Parameters

NameTypeDescription
id
Path, required
IntegerThe ID of a runner

Responses

CodeDescriptionSchema
200OKAPIEntitiesCiRunnerManager
400Bad Request—
403Forbidden—
404Not Found—

Get projects associated with a runner

GET /api/v4/runners/{id}/projects

Get a paginated list of all projects associated with the specified runner. Access is restricted based on user permissions.

Parameters

NameTypeDescription
id
Path, required
IntegerThe ID of a runner
page
Query
IntegerCurrent page number
Default: 1
Example: 1
per_page
Query
IntegerNumber of items per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKAPIEntitiesBasicProjectDetails
400Bad Request—
401Unauthorized—
403No access granted—
404Runner not found—

Reset an authentication token for a runner

POST /api/v4/runners/{id}/reset_authentication_token

Resets the authentication token for a specified runner.

Parameters

NameTypeDescription
id
Path, required
IntegerThe ID of the runner

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesCiResetTokenResult
400Bad Request—
403No access granted—
404Runner not found—
422Unprocessable Entity—

Create a runner owned by currently authenticated user

POST /api/v4/user/runners

Create a new runner

Request body (application/json)

PropertyTypeDescription
access_levelStringThe access level of the runner
Allowed values: not_protected, ref_protected
descriptionStringDescription of the runner
group_id
Required
IntegerThe ID of the group that the runner is created in
Example: 1
lockedBooleanSpecifies if the runner should be locked for the current project (defaults to false)
maintenance_noteStringFree-form maintenance notes for the runner (1024 characters)
maximum_timeoutIntegerMaximum timeout that limits the amount of time (in seconds) that runners can run jobs
pausedBooleanSpecifies if the runner should ignore new jobs (defaults to false)
project_id
Required
IntegerThe ID of the project that the runner is created in
Example: 1
run_untaggedBooleanSpecifies if the runner should handle untagged jobs (defaults to true)
runner_type
Required
StringSpecifies the scope of the runner
Allowed values: instance_type, group_type, project_type
Minimum length: 1
tag_listArray of stringsA list of runner tags

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesCiRunnerRegistrationDetails
400Bad Request—
403Forbidden—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesBasicGroupDetails

PropertyTypeDescription
idInteger (int64)—
nameStringExample: Diaspora
web_urlStringExample: http://gitlab.example.com/groups/diaspora

APIEntitiesBasicProjectDetails

PropertyTypeDescription
avatar_urlStringExample: http://example.com/uploads/project/avatar/3/uploads/avatar.png
created_atString (date-time)Example: 2020-05-07T04:27:17.016Z
custom_attributesAPIEntitiesCustomAttribute—
default_branchStringExample: main
descriptionStringExample: desc
forks_countIntegerExample: 1
http_url_to_repoStringExample: https://gitlab.example.com/gitlab/gitlab.git
idInteger (int64)Example: 1
last_activity_atString (date-time)Example: 2013-09-30T13:46:02Z
licenseAPIEntitiesLicenseBasic—
license_urlStringExample: https://gitlab.example.com/gitlab/gitlab/blob/master/LICENCE
nameStringExample: project1
name_with_namespaceStringExample: John Doe / project1
namespaceAPIEntitiesNamespaceBasic—
pathStringExample: project1
path_with_namespaceStringExample: namespace1/project1
readme_urlStringExample: https://gitlab.example.com/gitlab/gitlab/blob/master/README.md
repository_storageStringExample: default
ssh_url_to_repoStringExample: git@gitlab.example.com:gitlab/gitlab.git
star_countIntegerExample: 1
tag_listArray of stringsExample: ["tag"]
topicsArray of stringsExample: ["topic"]
visibilityStringExample: public
web_urlStringExample: https://gitlab.example.com/gitlab/gitlab

APIEntitiesCiJobBasicWithProject

PropertyTypeDescription
allow_failureBoolean—
commitAPIEntitiesCommit—
coverageNumber (float)Example: 98.29
created_atString (date-time)Example: 2015-12-24T15:51:21.880Z
durationNumber (float)Time spent running
Example: 0.465
erased_atString (date-time)Example: 2015-12-24T18:00:29.728Z
failure_reasonStringExample: script_failure
finished_atString (date-time)Example: 2015-12-24T17:54:31.198Z
idInteger (int64)Example: 1
nameStringExample: deploy_to_production
pipelineAPIEntitiesCiPipelineBasic—
projectAPIEntitiesProjectIdentity—
queued_durationNumber (float)Time spent enqueued
Example: 0.123
refStringExample: main
stageStringExample: deploy
started_atString (date-time)Example: 2015-12-24T17:54:30.733Z
statusStringExample: waiting_for_resource
tagBoolean—
userAPIEntitiesUser—
web_urlStringExample: https://example.com/foo/bar/-/jobs/1

APIEntitiesCiPipelineBasic

PropertyTypeDescription
created_atString (date-time)Example: 2022-10-21T16:49:48.000+02:00
idInteger (int64)Example: 1
iidIntegerExample: 2
project_idInteger (int64)Example: 3
refStringExample: feature-branch
shaStringExample: 0ec9e58fdfca6cdd6652c083c9edb53abc0bad52
sourceStringExample: push
statusStringExample: success
updated_atString (date-time)Example: 2022-10-21T16:49:48.000+02:00
web_urlStringExample: https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61

APIEntitiesCiResetTokenResult

PropertyTypeDescription
tokenString—
token_expires_atString—

APIEntitiesCiRunner

PropertyTypeDescription
activeBooleanExample: true
created_atString (date-time)Example: 2025-05-03T00:00:00.000Z
created_byAPIEntitiesUserBasic—
descriptionStringExample: test-1-20150125
idInteger (int64)Example: 8
ip_addressStringExample: 127.0.0.1
is_sharedBooleanExample: true
job_execution_statusStringAllowed values: active, idle
Example: idle
nameStringExample: test
onlineBooleanExample: true
pausedBooleanExample: false
runner_typeStringAllowed values: instance_type, group_type, project_type
Example: instance_type
statusStringExample: online

APIEntitiesCiRunnerDetails

PropertyTypeDescription
access_levelString—
activeBooleanExample: true
architectureString—
contacted_atString—
created_atString (date-time)Example: 2025-05-03T00:00:00.000Z
created_byAPIEntitiesUserBasic—
descriptionStringExample: test-1-20150125
groupsAPIEntitiesBasicGroupDetails—
idInteger (int64)Example: 8
ip_addressStringExample: 127.0.0.1
is_sharedBooleanExample: true
job_execution_statusStringAllowed values: active, idle
Example: idle
lockedString—
maintenance_noteString—
maximum_timeoutString—
nameStringExample: test
onlineBooleanExample: true
pausedBooleanExample: false
platformString—
projectsAPIEntitiesBasicProjectDetails—
revisionString—
run_untaggedString—
runner_typeStringAllowed values: instance_type, group_type, project_type
Example: instance_type
statusStringExample: online
tag_listString—
versionString—

APIEntitiesCiRunnerManager

PropertyTypeDescription
architectureStringExample: amd64
contacted_atStringExample: 2023-10-24T01:27:06.549Z
created_atStringExample: 2023-10-24T01:27:06.549Z
idInteger (int64)Example: 8
ip_addressStringExample: 127.0.0.1
job_execution_statusStringAllowed values: active, idle
Example: idle
platformStringExample: linux
revisionStringExample: 91a27b2a
statusStringExample: online
system_idStringExample: runner-1
versionStringExample: 16.11.0

APIEntitiesCiRunnerRegistrationDetails

PropertyTypeDescription
idString—
tokenString—
token_expires_atString—

APIEntitiesCommit

PropertyTypeDescription
author_emailStringExample: john@example.com
author_nameStringExample: John Smith
authored_dateString (date-time)Example: 2012-05-28T04:42:42-07:00
committed_dateString (date-time)Example: 2012-05-28T04:42:42-07:00
committer_emailStringExample: jack@example.com
committer_nameStringExample: Jack Smith
created_atString (date-time)Example: 2017-07-26T11:08:53.000+02:00
extended_trailersObjectExample: {"Signed-off-by":["John Doe \u003cjohndoe@gitlab.com\u003e","Jane Doe \u003cjanedoe@gitlab.com\u003e"]}
idStringExample: 2695effb5807a22ff3d138d593fd856244e155e7
messageStringExample: Initial commit
parent_idsArray of stringsExample: ["2a4b78934375d7f53875269ffd4f45fd83a84ebe"]
short_idStringExample: 2695effb
titleStringExample: Initial commit
trailersObjectExample: {"Merged-By":"Jane Doe janedoe@gitlab.com"}
web_urlStringExample: https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746

APIEntitiesCustomAttribute

PropertyTypeDescription
keyStringExample: foo
valueStringExample: bar

APIEntitiesLicenseBasic

PropertyTypeDescription
html_urlStringExample: http://choosealicense.com/licenses/gpl-3.0
keyStringExample: gpl-3.0
nameStringExample: GNU General Public License v3.0
nicknameStringExample: GNU GPLv3
source_urlString—

APIEntitiesNamespaceBasic

PropertyTypeDescription
avatar_urlStringExample: https://example.com/avatar/12345
full_pathStringExample: group/my_project
idInteger (int64)Example: 2
kindStringExample: project
nameStringExample: project
parent_idInteger (int64)Example: 1
pathStringExample: my_project
web_urlStringExample: https://example.com/group/my_project

APIEntitiesProjectIdentity

PropertyTypeDescription
created_atString (date-time)Example: 2020-05-07T04:27:17.016Z
descriptionStringExample: desc
idInteger (int64)Example: 1
nameStringExample: project1
name_with_namespaceStringExample: John Doe / project1
pathStringExample: project1
path_with_namespaceStringExample: namespace1/project1

APIEntitiesUser

PropertyTypeDescription
avatar_pathStringExample: /user/avatar/28/The-Big-Lebowski-400-400.png
avatar_urlStringExample: https://gravatar.com/avatar/1
bioString—
botBoolean—
created_atString—
custom_attributesArray of APIEntitiesCustomAttribute—
discordString—
followersString—
followingString—
githubString—
idInteger (int64)Example: 1
is_followedString—
job_titleString—
linkedinString—
local_timeString—
locationString—
lockedBoolean—
nameStringExample: Administrator
organizationString—
pronounsString—
public_emailStringExample: john@example.com
stateStringExample: active
twitterString—
usernameStringExample: admin
web_urlStringExample: https://gitlab.example.com/root
website_urlString—
work_informationString—

APIEntitiesUserBasic

PropertyTypeDescription
avatar_pathStringExample: /user/avatar/28/The-Big-Lebowski-400-400.png
avatar_urlStringExample: https://gravatar.com/avatar/1
custom_attributesArray of APIEntitiesCustomAttribute—
idInteger (int64)Example: 1
lockedBoolean—
nameStringExample: Administrator
public_emailStringExample: john@example.com
stateStringExample: active
usernameStringExample: admin
web_urlStringExample: https://gitlab.example.com/root