Runners API

Pagination is available on the following API endpoints (they return 20 items by default):

GET /runners
GET /runners/all
GET /runners/:id/jobs
GET /projects/:id/runners
GET /groups/:id/runners

Registration and authentication tokens

There are two tokens to take into account when connecting a runner with GitLab.

TokenDescription
Registration tokenToken used to register the runner. It can be obtained through GitLab.
Authentication tokenToken used to authenticate the runner with the GitLab instance. It is obtained automatically when you register a runner or by the Runner API when you manually register a runner or reset the authentication token. You can also obtain the authentication token using Create a runner API method.

Here’s an example of how the two tokens are used in runner registration:

  1. You register the runner via the GitLab API using a registration token, and an authentication token is returned.

  2. You use that authentication token and add it to the runner’s configuration file:

    [[runners]]
  token = "<authentication_token>"

GitLab and the runner are then connected.

List owned runners

Get a list of runners available to the user.

GET /runners
GET /runners?scope=active
GET /runners?type=project_type
GET /runners?status=online
GET /runners?paused=true
GET /runners?tag_list=tag1,tag2
AttributeTypeRequiredDescription
scopestringnoDeprecated: Use type or status instead. The scope of runners to return, one of: active, paused, online and offline; showing all runners if none provided
typestringnoThe type of runners to return, one of: instance_type, group_type, project_type
statusstringnoThe status of runners to return, one of: online, offline, stale, and never_contacted. active and paused are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0
pausedbooleannoWhether to include only runners that are accepting or ignoring new jobs
tag_liststring arraynoA list of runner tags
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"
note
The active and paused values in the status query parameter were deprecated in GitLab 14.8. and will be removed in GitLab 16.0. They are replaced by the paused query parameter.
note
The active attribute in the response was deprecated in GitLab 14.8. and will be removed in GitLab 16.0. It is replaced by the paused attribute.

Example response:

[
    {
        "active": true,
        "paused": false,
        "description": "test-1-20150125",
        "id": 6,
        "ip_address": "127.0.0.1",
        "is_shared": false,
        "runner_type": "project_type",
        "name": null,
        "online": true,
        "status": "online"
    },
    {
        "active": true,
        "paused": false,
        "description": "test-2-20150125",
        "id": 8,
        "ip_address": "127.0.0.1",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline"
    }
]

List all runners

Get a list of all runners in the GitLab instance (project and shared). Access is restricted to users with administrator access.

GET /runners/all
GET /runners/all?scope=online
GET /runners/all?type=project_type
GET /runners/all?status=online
GET /runners/all?paused=true
GET /runners/all?tag_list=tag1,tag2
AttributeTypeRequiredDescription
scopestringnoDeprecated: Use type or status instead. The scope of runners to return, one of: specific, shared, active, paused, online and offline; showing all runners if none provided
typestringnoThe type of runners to return, one of: instance_type, group_type, project_type
statusstringnoThe status of runners to return, one of: online, offline, stale, and never_contacted. active and paused are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0
pausedbooleannoWhether to include only runners that are accepting or ignoring new jobs
tag_liststring arraynoA list of runner tags
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all"
note
The active and paused values in the status query parameter were deprecated in GitLab 14.8. and will be removed in GitLab 16.0. They are replaced by the paused query parameter.
note
The active attribute in the response was deprecated in GitLab 14.8. and will be removed in GitLab 16.0. It is replaced by the paused attribute.

Example response:

[
    {
        "active": true,
        "paused": false,
        "description": "shared-runner-1",
        "id": 1,
        "ip_address": "127.0.0.1",
        "is_shared": true,
        "runner_type": "instance_type",
        "name": null,
        "online": true,
        "status": "online"
    },
    {
        "active": true,
        "paused": false,
        "description": "shared-runner-2",
        "id": 3,
        "ip_address": "127.0.0.1",
        "is_shared": true,
        "runner_type": "instance_type",
        "name": null,
        "online": false,
        "status": "offline"
    },
    {
        "active": true,
        "paused": false,
        "description": "test-1-20150125",
        "id": 6,
        "ip_address": "127.0.0.1",
        "is_shared": false,
        "runner_type": "project_type",
        "name": null,
        "online": true,
        "status": "paused"
    },
    {
        "active": true,
        "paused": false,
        "description": "test-2-20150125",
        "id": 8,
        "ip_address": "127.0.0.1",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline"
    }
]

To view more than the first 20 runners, use pagination.

Get runner’s details

Get details of a runner.

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 authenticated users.

GET /runners/:id
AttributeTypeRequiredDescription
idintegeryesThe ID of a runner
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"
note
The token attribute in the response was deprecated in GitLab 12.10. and removed in GitLab 13.0.
note
The active attribute in the response was deprecated in GitLab 14.8. and will be removed in GitLab 16.0. It is replaced by the paused attribute.

Example response:

{
    "active": true,
    "paused": false,
    "architecture": null,
    "description": "test-1-20150125",
    "id": 6,
    "ip_address": "127.0.0.1",
    "is_shared": false,
    "runner_type": "project_type",
    "contacted_at": "2016-01-25T16:39:48.066Z",
    "name": null,
    "online": true,
    "status": "online",
    "platform": null,
    "projects": [
        {
            "id": 1,
            "name": "GitLab Community Edition",
            "name_with_namespace": "GitLab.org / GitLab Community Edition",
            "path": "gitlab-foss",
            "path_with_namespace": "gitlab-org/gitlab-foss"
        }
    ],
    "revision": null,
    "tag_list": [
        "ruby",
        "mysql"
    ],
    "version": null,
    "access_level": "ref_protected",
    "maximum_timeout": 3600
}

Update runner’s details

Update details of a runner.

PUT /runners/:id
AttributeTypeRequiredDescription
idintegeryesThe ID of a runner
descriptionstringnoThe description of the runner
activebooleannoDeprecated: Use paused instead. Flag indicating whether the runner is allowed to receive jobs
pausedbooleannoSpecifies if the runner should ignore new jobs
tag_listarraynoThe list of tags for the runner
run_untaggedbooleannoSpecifies if the runner can execute untagged jobs
lockedbooleannoSpecifies if the runner is locked
access_levelstringnoThe access level of the runner; not_protected or ref_protected
maximum_timeoutintegernoMaximum timeout that limits the amount of time (in seconds) that runners can run jobs
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6" \
     --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2"
note
The token attribute in the response was deprecated in GitLab 12.10. and removed in GitLab 13.0.
note
The active query parameter was deprecated in GitLab 14.8. and will be removed in GitLab 16.0. It is replaced by the paused attribute.

Example response:

{
    "active": true,
    "architecture": null,
    "description": "test-1-20150125-test",
    "id": 6,
    "ip_address": "127.0.0.1",
    "is_shared": false,
    "runner_type": "group_type",
    "contacted_at": "2016-01-25T16:39:48.066Z",
    "name": null,
    "online": true,
    "status": "online",
    "platform": null,
    "projects": [
        {
            "id": 1,
            "name": "GitLab Community Edition",
            "name_with_namespace": "GitLab.org / GitLab Community Edition",
            "path": "gitlab-foss",
            "path_with_namespace": "gitlab-org/gitlab-foss"
        }
    ],
    "revision": null,
    "tag_list": [
        "ruby",
        "mysql",
        "tag1",
        "tag2"
    ],
    "version": null,
    "access_level": "ref_protected",
    "maximum_timeout": null
}

Pause a runner

Pause a runner.

PUT --form "paused=true" /runners/:runner_id

# --or--

# Deprecated: removal planned in 16.0
PUT --form "active=false" /runners/:runner_id
AttributeTypeRequiredDescription
runner_idintegeryesThe ID of a runner
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "paused=true"  "https://gitlab.example.com/api/v4/runners/6"

# --or--

# Deprecated: removal planned in 16.0
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "active=false"  "https://gitlab.example.com/api/v4/runners/6"
note
The active form attribute was deprecated in GitLab 14.8. and will be removed in GitLab 16.0. It is replaced by the paused attribute.

List runner’s jobs

Introduced in GitLab 10.3.

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.

GET /runners/:id/jobs
AttributeTypeRequiredDescription
idintegeryesThe ID of a runner
statusstringnoStatus of the job; one of: running, success, failed, canceled
order_bystringnoOrder jobs by id
sortstringnoSort jobs in asc or desc order (default: desc). Specify order_by as well, including for id.
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/1/jobs?status=running"

Example response:

[
    {
        "id": 2,
        "ip_address": "127.0.0.1",
        "status": "running",
        "stage": "test",
        "name": "test",
        "ref": "main",
        "tag": false,
        "coverage": null,
        "created_at": "2017-11-16T08:50:29.000Z",
        "started_at": "2017-11-16T08:51:29.000Z",
        "finished_at": "2017-11-16T08:53:29.000Z",
        "duration": 120,
        "user": {
            "id": 1,
            "name": "John Doe2",
            "username": "user2",
            "state": "active",
            "avatar_url": "http://www.gravatar.com/avatar/c922747a93b40d1ea88262bf1aebee62?s=80&d=identicon",
            "web_url": "http://localhost/user2",
            "created_at": "2017-11-16T18:38:46.000Z",
            "bio": null,
            "location": null,
            "public_email": "",
            "skype": "",
            "linkedin": "",
            "twitter": "",
            "website_url": "",
            "organization": null
        },
        "commit": {
            "id": "97de212e80737a608d939f648d959671fb0a0142",
            "short_id": "97de212e",
            "title": "Update configuration\r",
            "created_at": "2017-11-16T08:50:28.000Z",
            "parent_ids": [
                "1b12f15a11fc6e62177bef08f47bc7b5ce50b141",
                "498214de67004b1da3d820901307bed2a68a8ef6"
            ],
            "message": "See merge request !123",
            "author_name": "John Doe2",
            "author_email": "user2@example.org",
            "authored_date": "2017-11-16T08:50:27.000Z",
            "committer_name": "John Doe2",
            "committer_email": "user2@example.org",
            "committed_date": "2017-11-16T08:50:27.000Z"
        },
        "pipeline": {
            "id": 2,
            "sha": "97de212e80737a608d939f648d959671fb0a0142",
            "ref": "main",
            "status": "running"
        },
        "project": {
            "id": 1,
            "description": null,
            "name": "project1",
            "name_with_namespace": "John Doe2 / project1",
            "path": "project1",
            "path_with_namespace": "namespace1/project1",
            "created_at": "2017-11-16T18:38:46.620Z"
        }
    }
]

List project’s runners

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

GET /projects/:id/runners
GET /projects/:id/runners?scope=active
GET /projects/:id/runners?type=project_type
GET /projects/:id/runners/all?status=online
GET /projects/:id/runners/all?paused=true
GET /projects/:id/runners?tag_list=tag1,tag2
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project owned by the authenticated user
scopestringnoDeprecated: Use type or status instead. The scope of runners to return, one of: active, paused, online and offline; showing all runners if none provided
typestringnoThe type of runners to return, one of: instance_type, group_type, project_type
statusstringnoThe status of runners to return, one of: online, offline, stale, and never_contacted. active and paused are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0
pausedbooleannoWhether to include only runners that are accepting or ignoring new jobs
tag_liststring arraynoA list of runner tags
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners"
note
The active and paused values in the status query parameter were deprecated in GitLab 14.8. and will be removed in GitLab 16.0. They are replaced by the paused query parameter.
note
The active attribute in the response was deprecated in GitLab 14.8. and will be removed in GitLab 16.0. It is replaced by the paused attribute.

Example response:

[
    {
        "active": true,
        "paused": false,
        "description": "test-2-20150125",
        "id": 8,
        "ip_address": "127.0.0.1",
        "is_shared": false,
        "runner_type": "project_type",
        "name": null,
        "online": false,
        "status": "offline"
    },
    {
        "active": true,
        "paused": false,
        "description": "development_runner",
        "id": 5,
        "ip_address": "127.0.0.1",
        "is_shared": true,
        "runner_type": "instance_type",
        "name": null,
        "online": true,
        "status": "online"
    }
]

Enable a runner in project

Enable an available project runner in the project.

POST /projects/:id/runners
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project owned by the authenticated user
runner_idintegeryesThe ID of a runner
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners" \
     --form "runner_id=9"

Example response:

{
    "active": true,
    "description": "test-2016-02-01",
    "id": 9,
    "ip_address": "127.0.0.1",
    "is_shared": false,
    "runner_type": "project_type",
    "name": null,
    "online": true,
    "status": "online"
}

Disable a runner from project

Disable a project runner from the project. It works only if the project isn’t the only project associated with the specified runner. If so, an error is returned. Use the call to delete a runner instead.

DELETE /projects/:id/runners/:runner_id
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project owned by the authenticated user
runner_idintegeryesThe ID of a runner
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners/9"

List group’s runners

List all runners available in the group as well as its ancestor groups, including any allowed shared runners.

GET /groups/:id/runners
GET /groups/:id/runners?type=group_type
GET /groups/:id/runners/all?status=online
GET /groups/:id/runners/all?paused=true
GET /groups/:id/runners?tag_list=tag1,tag2
AttributeTypeRequiredDescription
idintegeryesThe ID of the group owned by the authenticated user
typestringnoThe type of runners to return, one of: instance_type, group_type, project_type. The project_type value is deprecated and will be removed in GitLab 15.0
statusstringnoThe status of runners to return, one of: online, offline, stale, and never_contacted. active and paused are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0
pausedbooleannoWhether to include only runners that are accepting or ignoring new jobs
tag_liststring arraynoA list of runner tags
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/9/runners"
note
The active and paused values in the status query parameter were deprecated in GitLab 14.8. and will be removed in GitLab 16.0. They are replaced by the paused query parameter.
note
The active attribute in the response was deprecated in GitLab 14.8. and will be removed in GitLab 16.0. It is replaced by the paused attribute.

Example response:

[
  {
    "id": 3,
    "description": "Shared",
    "ip_address": "127.0.0.1",
    "active": true,
    "paused": false,
    "is_shared": true,
    "runner_type": "instance_type",
    "name": "gitlab-runner",
    "online": null,
    "status": "never_contacted"
  },
  {
    "id": 6,
    "description": "Test",
    "ip_address": "127.0.0.1",
    "active": true,
    "paused": false,
    "is_shared": true,
    "runner_type": "instance_type",
    "name": "gitlab-runner",
    "online": false,
    "status": "offline"
  },
  {
    "id": 8,
    "description": "Test 2",
    "ip_address": "127.0.0.1",
    "active": true,
    "paused": false,
    "is_shared": false,
    "runner_type": "group_type",
    "name": "gitlab-runner",
    "online": null,
    "status": "never_contacted"
  }
]

Register a new runner

Register a new runner for the instance.

POST /runners
AttributeTypeRequiredDescription
tokenstringyesRegistration token
descriptionstringnoDescription of the runner
infohashnoRunner’s metadata. You can include name, version, revision, platform, and architecture, but only version, platform, and architecture are displayed in the Admin Area of the UI
activebooleannoDeprecated: Use paused instead. Specifies if the runner is allowed to receive new jobs
pausedbooleannoSpecifies if the runner should ignore new jobs
lockedbooleannoSpecifies if the runner should be locked for the current project
run_untaggedbooleannoSpecifies if the runner should handle untagged jobs
tag_liststring arraynoA list of runner tags
access_levelstringnoThe access level of the runner; not_protected or ref_protected
maximum_timeoutintegernoMaximum timeout that limits the amount of time (in seconds) that runners can run jobs
maintainer_notestringno Deprecated, see maintenance_note
maintenance_notestringnoFree-form maintenance notes for the runner (1024 characters)
curl --request POST "https://gitlab.example.com/api/v4/runners" \
     --form "token=<registration_token>" --form "description=test-1-20150125-test" \
     --form "tag_list=ruby,mysql,tag1,tag2"

Response:

StatusDescription
201Runner was created
403Invalid runner registration token
410Runner registration disabled

Example response:

{
    "id": 12345,
    "token": "6337ff461c94fd3fa32ba3b1ff4125",
    "token_expires_at": "2021-09-27T21:05:03.203Z"
}

Delete a runner

There are two ways to delete a runner:

  • By specifying the runner ID.
  • By specifying the runner’s authentication token.

Delete a runner by ID

To delete the runner by ID, use your access token with the runner’s ID:

DELETE /runners/:id
AttributeTypeRequiredDescription
idintegeryesThe ID of a runner. The ID is visible in the UI under Settings > CI/CD. Expand Runners, and below the Remove Runner button is an ID preceded by the pound sign, for example, #6.
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"

Delete a runner by authentication token

To delete the runner by using its authentication token:

DELETE /runners
AttributeTypeRequiredDescription
tokenstringyesThe runner’s authentication token.
curl --request DELETE "https://gitlab.example.com/api/v4/runners" \
     --form "token=<authentication_token>"

Response:

StatusDescription
204Runner was deleted

Verify authentication for a registered runner

Validates authentication credentials for a registered runner.

POST /runners/verify
AttributeTypeRequiredDescription
tokenstringyesThe runner’s authentication token.
system_idstringnoThe runner’s system identifier. This attribute is required if the token starts with glrt-.
curl --request POST "https://gitlab.example.com/api/v4/runners/verify" \
     --form "token=<authentication_token>"

Response:

StatusDescription
200Credentials are valid
403Credentials are invalid

Example response:

{
    "id": 12345,
    "token": "glrt-6337ff461c94fd3fa32ba3b1ff4125",
    "token_expires_at": "2021-09-27T21:05:03.203Z"
}

Reset instance’s runner registration token

Introduced in GitLab 14.3.

caution
Runner registration tokens, and support for certain configuration arguments, were deprecated in GitLab 15.6 and will be removed in GitLab 17.0. After GitLab 17.0, you will no longer be able to reset runner registration tokens and the reset_registration_token endpoint will not function.

Reset the runner registration token for the GitLab instance.

POST /runners/reset_registration_token

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/runners/reset_registration_token"

Reset project’s runner registration token

Introduced in GitLab 14.3.

caution
Runner registration tokens, and support for certain configuration arguments, were deprecated in GitLab 15.6 and will be removed in GitLab 17.0. After GitLab 17.0, you will no longer be able to reset runner registration tokens and the reset_registration_token endpoint will not function.

Reset the runner registration token for a project.

POST /projects/:id/runners/reset_registration_token

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/9/runners/reset_registration_token"

Reset group’s runner registration token

Introduced in GitLab 14.3.

caution
Runner registration tokens, and support for certain configuration arguments, were deprecated in GitLab 15.6 and will be removed in GitLab 17.0. After GitLab 17.0, you will no longer be able to reset runner registration tokens and the reset_registration_token endpoint will not function.

Reset the runner registration token for a group.

POST /groups/:id/runners/reset_registration_token

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/9/runners/reset_registration_token"

Reset runner’s authentication token by using the runner ID

Reset the runner’s authentication token by using its runner ID.

POST /runners/:id/reset_authentication_token
AttributeTypeRequiredDescription
idintegeryesThe ID of a runner
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/runners/1/reset_authentication_token"

Example response:

{
    "token": "6337ff461c94fd3fa32ba3b1ff4125",
    "token_expires_at": "2021-09-27T21:05:03.203Z"
}

Reset runner’s authentication token by using the current token

Reset the runner’s authentication token by using the current token’s value as an input.

POST /runners/reset_authentication_token
AttributeTypeRequiredDescription
tokenstringyesThe authentication token of the runner
curl --request POST --form "token=<current token>" \
     "https://gitlab.example.com/api/v4/runners/reset_authentication_token"

Example response:

{
    "token": "6337ff461c94fd3fa32ba3b1ff4125",
    "token_expires_at": "2021-09-27T21:05:03.203Z"
}