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
| Name | Type | Description |
|---|---|---|
idPath, | String | The ID of a group |
typeQuery | String | The type of runners to return Allowed values: instance_,group_,project_ |
pausedQuery | Boolean | Whether to include only runners that are accepting or ignoring new jobs |
statusQuery | String | The status of runners to return Allowed values: active,paused,online,offline,never_,stale |
tag_Query | Array of strings | A list of runner tags Example: ["macos", |
version_Query | String | The version prefix of runners to return Pattern: (?<=^|\n(?!$))[\d+.Example: 15. |
pageQuery | Integer | Current page number Default: 1Example: 1 |
per_Query | Integer | Number of items per page Default: 20Example: 20 |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Scope contains invalid value | — |
403 | Forbidden | — |
404 | Not Found | — |
Reset runner registration token
POST /api/v4/groups/{id}/runners/reset_registration_token
FE version
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String | The ID of a group |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
403 | Forbidden | — |
404 | Group 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
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | The ID or URL- |
scopeQuery | String | Deprecated:type or status instead.Allowed values: specific,shared,instance_,group_,project_,active,paused,online,offline,never_,stale |
typeQuery | String | The type of runners to return Allowed values: instance_,group_,project_ |
pausedQuery | Boolean | Whether to include only runners that are accepting or ignoring new jobs |
statusQuery | String | The status of runners to return Allowed values: active,paused,online,offline,never_,stale |
tag_Query | Array of strings | A list of runner tags Example: ["macos", |
version_Query | String | The version prefix of runners to return Pattern: (?<=^|\n(?!$))[\d+.Example: 15. |
pageQuery | Integer | Current page number Default: 1Example: 1 |
per_Query | Integer | Number of items per page Default: 20Example: 20 |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Scope contains invalid value | — |
403 | No access granted | — |
404 | Not Found | — |
Assign a runner to a project
POST /api/v4/projects/{id}/runners
Assigns an available project runner to a project.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | The ID or URL- |
Request body (application/json)
| Property | Type | Description |
|---|---|---|
runner_Required | Integer | The ID of a runner |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad Request | — |
403 | Runner is locked | — |
404 | Runner not found | — |
Reset runner registration token
POST /api/v4/projects/{id}/runners/reset_registration_token
FE version
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String | The ID of a project |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
403 | Forbidden | — |
404 | Project 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
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | The ID or URL- |
runner_Path, | Integer | The ID of a runner |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
403 | You cannot unassign a runner from the owner project. | — |
404 | Runner not found | — |
412 | Precondition 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
| Name | Type | Description |
|---|---|---|
scopeQuery | String | Deprecated:type or status instead.Allowed values: specific,shared,instance_,group_,project_,active,paused,online,offline,never_,stale |
typeQuery | String | The type of runners to return Allowed values: instance_,group_,project_ |
pausedQuery | Boolean | Whether to include only runners that are accepting or ignoring new jobs |
statusQuery | String | The status of runners to return Allowed values: active,paused,online,offline,never_,stale |
tag_Query | Array of strings | A list of runner tags Example: ["macos", |
version_Query | String | The version prefix of runners to return Pattern: (?<=^|\n(?!$))[\d+.Example: 15. |
pageQuery | Integer | Current page number Default: 1Example: 1 |
per_Query | Integer | Number of items per page Default: 20Example: 20 |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Scope contains invalid value | — |
401 | Unauthorized | — |
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
| Name | Type | Description |
|---|---|---|
scopeQuery | String | Deprecated:type or status instead.Allowed values: specific,shared,instance_,group_,project_,active,paused,online,offline,never_,stale |
typeQuery | String | The type of runners to return Allowed values: instance_,group_,project_ |
pausedQuery | Boolean | Whether to include only runners that are accepting or ignoring new jobs |
statusQuery | String | The status of runners to return Allowed values: active,paused,online,offline,never_,stale |
tag_Query | Array of strings | A list of runner tags Example: ["macos", |
version_Query | String | The version prefix of runners to return Pattern: (?<=^|\n(?!$))[\d+.Example: 15. |
pageQuery | Integer | Current page number Default: 1Example: 1 |
per_Query | Integer | Number of items per page Default: 20Example: 20 |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Scope contains invalid value | — |
401 | Unauthorized | — |
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
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad Request | — |
403 | Forbidden | — |
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
| Name | Type | Description |
|---|---|---|
idPath, | Integer | The ID of a runner |
include_Query | Boolean | Include projects in the response. Default: true |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
403 | No access granted | — |
404 | Runner not found | — |
Update a runner
PUT /api/v4/runners/{id}
Updates a specified runner.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | Integer | The ID of a runner |
Request body (application/json)
| Property | Type | Description |
|---|---|---|
access_ | String | The access level of the runner Allowed values: not_,ref_ |
active | Boolean | Deprecated:paused instead.paused |
description | String | The description of the runner |
locked | Boolean | Specifies if the runner is locked |
maintenance_ | String | Free- |
maximum_ | Integer | Maximum timeout that limits the amount of time (in seconds) that runners can run jobs |
paused | Boolean | Specifies if the runner should ignore new jobs.active |
run_ | Boolean | Specifies if the runner can execute untagged jobs |
tag_ | Array of strings | The list of tags for a runner |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
403 | No access granted | — |
404 | Runner not found | — |
Delete a runner
DELETE /api/v4/runners/{id}
Deletes a specified runner.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | Integer | The ID of a runner |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
403 | Runner associated with more than one project | — |
404 | Runner not found | — |
412 | Precondition 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
| Name | Type | Description |
|---|---|---|
idPath, | Integer | The ID of a runner |
system_Query | String | System ID associated with the runner manager |
statusQuery | String | Status of the job Allowed values: created,waiting_,preparing,waiting_,pending,running,success,failed,canceling,canceled,skipped,manual,scheduled |
order_Query | String | Order by idAllowed values: id |
sortQuery | String | Sort by asc or desc order.order_ as well,idAllowed values: asc,descDefault: desc |
cursorQuery | String | Cursor for obtaining the next set of records |
pageQuery | Integer | Current page number Default: 1Example: 1 |
per_Query | Integer | Number of items per page Default: 20Example: 20 |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
403 | No access granted | — |
404 | Runner not found | — |
List all managers for a runner
GET /api/v4/runners/{id}/managers
List all managers for a specified runner.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | Integer | The ID of a runner |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
403 | Forbidden | — |
404 | Not 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
| Name | Type | Description |
|---|---|---|
idPath, | Integer | The ID of a runner |
pageQuery | Integer | Current page number Default: 1Example: 1 |
per_Query | Integer | Number of items per page Default: 20Example: 20 |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
403 | No access granted | — |
404 | Runner 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
| Name | Type | Description |
|---|---|---|
idPath, | Integer | The ID of the runner |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad Request | — |
403 | No access granted | — |
404 | Runner not found | — |
422 | Unprocessable Entity | — |
Create a runner owned by currently authenticated user
POST /api/v4/user/runners
Create a new runner
Request body (application/json)
| Property | Type | Description |
|---|---|---|
access_ | String | The access level of the runner Allowed values: not_,ref_ |
description | String | Description of the runner |
group_Required | Integer | The ID of the group that the runner is created in Example: 1 |
locked | Boolean | Specifies if the runner should be locked for the current project (defaults to false) |
maintenance_ | String | Free- |
maximum_ | Integer | Maximum timeout that limits the amount of time (in seconds) that runners can run jobs |
paused | Boolean | Specifies if the runner should ignore new jobs (defaults to false) |
project_Required | Integer | The ID of the project that the runner is created in Example: 1 |
run_ | Boolean | Specifies if the runner should handle untagged jobs (defaults to true) |
runner_Required | String | Specifies the scope of the runner Allowed values: instance_,group_,project_Minimum length: 1 |
tag_ | Array of strings | A list of runner tags |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad Request | — |
403 | Forbidden | — |
Schemas
Objects returned by the operations above and objects nested in their request bodies.
APIEntitiesBasicGroupDetails
| Property | Type | Description |
|---|---|---|
id | Integer (int64) | — |
name | String | Example:Diaspora |
web_ | String | Example:http: |
APIEntitiesBasicProjectDetails
| Property | Type | Description |
|---|---|---|
avatar_ | String | Example:http: |
created_ | String (date- | Example:2020- |
custom_ | APIEntities | — |
default_ | String | Example:main |
description | String | Example:desc |
forks_ | Integer | Example:1 |
http_ | String | Example:https: |
id | Integer (int64) | Example:1 |
last_ | String (date- | Example:2013- |
license | APIEntities | — |
license_ | String | Example:https: |
name | String | Example:project1 |
name_ | String | Example:John Doe / |
namespace | APIEntities | — |
path | String | Example:project1 |
path_ | String | Example:namespace1/ |
readme_ | String | Example:https: |
repository_ | String | Example:default |
ssh_ | String | Example:git@gitlab. |
star_ | Integer | Example:1 |
tag_ | Array of strings | Example:["tag"] |
topics | Array of strings | Example:["topic"] |
visibility | String | Example:public |
web_ | String | Example:https: |
APIEntitiesCiJobBasicWithProject
| Property | Type | Description |
|---|---|---|
allow_ | Boolean | — |
commit | APIEntities | — |
coverage | Number (float) | Example:98. |
created_ | String (date- | Example:2015- |
duration | Number (float) | Time spent running Example: 0. |
erased_ | String (date- | Example:2015- |
failure_ | String | Example:script_ |
finished_ | String (date- | Example:2015- |
id | Integer (int64) | Example:1 |
name | String | Example:deploy_ |
pipeline | APIEntities | — |
project | APIEntities | — |
queued_ | Number (float) | Time spent enqueued Example: 0. |
ref | String | Example:main |
stage | String | Example:deploy |
started_ | String (date- | Example:2015- |
status | String | Example:waiting_ |
tag | Boolean | — |
user | APIEntities | — |
web_ | String | Example:https: |
APIEntitiesCiPipelineBasic
| Property | Type | Description |
|---|---|---|
created_ | String (date- | Example:2022- |
id | Integer (int64) | Example:1 |
iid | Integer | Example:2 |
project_ | Integer (int64) | Example:3 |
ref | String | Example:feature- |
sha | String | Example:0ec9e58fdfca6cdd6652 |
source | String | Example:push |
status | String | Example:success |
updated_ | String (date- | Example:2022- |
web_ | String | Example:https: |
APIEntitiesCiResetTokenResult
| Property | Type | Description |
|---|---|---|
token | String | — |
token_ | String | — |
APIEntitiesCiRunner
| Property | Type | Description |
|---|---|---|
active | Boolean | Example:true |
created_ | String (date- | Example:2025- |
created_ | APIEntities | — |
description | String | Example:test- |
id | Integer (int64) | Example:8 |
ip_ | String | Example:127. |
is_ | Boolean | Example:true |
job_ | String | Allowed values:active,idleExample: idle |
name | String | Example:test |
online | Boolean | Example:true |
paused | Boolean | Example:false |
runner_ | String | Allowed values:instance_,group_,project_Example: instance_ |
status | String | Example:online |
APIEntitiesCiRunnerDetails
| Property | Type | Description |
|---|---|---|
access_ | String | — |
active | Boolean | Example:true |
architecture | String | — |
contacted_ | String | — |
created_ | String (date- | Example:2025- |
created_ | APIEntities | — |
description | String | Example:test- |
groups | APIEntities | — |
id | Integer (int64) | Example:8 |
ip_ | String | Example:127. |
is_ | Boolean | Example:true |
job_ | String | Allowed values:active,idleExample: idle |
locked | String | — |
maintenance_ | String | — |
maximum_ | String | — |
name | String | Example:test |
online | Boolean | Example:true |
paused | Boolean | Example:false |
platform | String | — |
projects | APIEntities | — |
revision | String | — |
run_ | String | — |
runner_ | String | Allowed values:instance_,group_,project_Example: instance_ |
status | String | Example:online |
tag_ | String | — |
version | String | — |
APIEntitiesCiRunnerManager
| Property | Type | Description |
|---|---|---|
architecture | String | Example:amd64 |
contacted_ | String | Example:2023- |
created_ | String | Example:2023- |
id | Integer (int64) | Example:8 |
ip_ | String | Example:127. |
job_ | String | Allowed values:active,idleExample: idle |
platform | String | Example:linux |
revision | String | Example:91a27b2a |
status | String | Example:online |
system_ | String | Example:runner- |
version | String | Example:16. |
APIEntitiesCiRunnerRegistrationDetails
| Property | Type | Description |
|---|---|---|
id | String | — |
token | String | — |
token_ | String | — |
APIEntitiesCommit
| Property | Type | Description |
|---|---|---|
author_ | String | Example:john@example. |
author_ | String | Example:John Smith |
authored_ | String (date- | Example:2012- |
committed_ | String (date- | Example:2012- |
committer_ | String | Example:jack@example. |
committer_ | String | Example:Jack Smith |
created_ | String (date- | Example:2017- |
extended_ | Object | Example:{"Signed- |
id | String | Example:2695effb5807a22ff3d1 |
message | String | Example:Initial commit |
parent_ | Array of strings | Example:["2a4b78934375d7f53875 |
short_ | String | Example:2695effb |
title | String | Example:Initial commit |
trailers | Object | Example:{"Merged- |
web_ | String | Example:https: |
APIEntitiesCustomAttribute
| Property | Type | Description |
|---|---|---|
key | String | Example:foo |
value | String | Example:bar |
APIEntitiesLicenseBasic
| Property | Type | Description |
|---|---|---|
html_ | String | Example:http: |
key | String | Example:gpl- |
name | String | Example:GNU General Public License v3. |
nickname | String | Example:GNU GPLv3 |
source_ | String | — |
APIEntitiesNamespaceBasic
| Property | Type | Description |
|---|---|---|
avatar_ | String | Example:https: |
full_ | String | Example:group/ |
id | Integer (int64) | Example:2 |
kind | String | Example:project |
name | String | Example:project |
parent_ | Integer (int64) | Example:1 |
path | String | Example:my_ |
web_ | String | Example:https: |
APIEntitiesProjectIdentity
| Property | Type | Description |
|---|---|---|
created_ | String (date- | Example:2020- |
description | String | Example:desc |
id | Integer (int64) | Example:1 |
name | String | Example:project1 |
name_ | String | Example:John Doe / |
path | String | Example:project1 |
path_ | String | Example:namespace1/ |
APIEntitiesUser
| Property | Type | Description |
|---|---|---|
avatar_ | String | Example:/ |
avatar_ | String | Example:https: |
bio | String | — |
bot | Boolean | — |
created_ | String | — |
custom_ | Array of APIEntities | — |
discord | String | — |
followers | String | — |
following | String | — |
github | String | — |
id | Integer (int64) | Example:1 |
is_ | String | — |
job_ | String | — |
linkedin | String | — |
local_ | String | — |
location | String | — |
locked | Boolean | — |
name | String | Example:Administrator |
organization | String | — |
pronouns | String | — |
public_ | String | Example:john@example. |
state | String | Example:active |
twitter | String | — |
username | String | Example:admin |
web_ | String | Example:https: |
website_ | String | — |
work_ | String | — |
APIEntitiesUserBasic
| Property | Type | Description |
|---|---|---|
avatar_ | String | Example:/ |
avatar_ | String | Example:https: |
custom_ | Array of APIEntities | — |
id | Integer (int64) | Example:1 |
locked | Boolean | — |
name | String | Example:Administrator |
public_ | String | Example:john@example. |
state | String | Example:active |
username | String | Example:admin |
web_ | String | Example:https: |