Skip to content

Runners API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

This page describes endpoints for runners registered to an instance. To create a runner linked to the current user, see Create a runner.

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

To connect a runner with GitLab, you need two tokens.

Token Description
Registration token Token used to register the runner. It can be obtained through GitLab.
Authentication token Token used to authenticate the runner with the GitLab instance. The token is obtained automatically when you register a runner or by the Runners API when you manually register a runner or reset the authentication token. You can also obtain the token by using the POST /user/runners endpoint.

Here's an example of how you can use the tokens for runner registration:

  1. Register the runner by using the GitLab API with a registration token to receive an authentication token.

  2. Add the authentication token 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.

Prerequisites:

  • You must be an administrator of or have the Owner role for the target namespace or project.
  • For instance_type, you must be an administrator of the GitLab instance.
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
Attribute Type Required Description
scope string no Deprecated: Use type or status instead. The scope of runners to return, one of: active, paused, online and offline; showing all runners if none provided
type string no The type of runners to return, one of: instance_type, group_type, project_type
status string no The status of runners to return, one of: online, offline, stale, or never_contacted.
Other possible values are the deprecated active and paused.
Requesting offline runners might also return stale runners because stale is included in offline.
paused boolean no Whether to include only runners that are accepting or ignoring new jobs
tag_list string array no A list of runner tags
version_prefix string no The prefix of the version of the runners to return. For example, 15.0, 14, 16.1.241 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"

The active and paused values in the status query parameter are deprecated and scheduled for removal in a future version of the REST API. Use the paused query parameter instead.

The active attribute in the response is deprecated and is scheduled for removal in a future version of the REST API. Use the paused attribute instead.

The ip_address attribute in the response is deprecated in GitLab 16.1 and is scheduled for removal in a future version of the REST API. In GitLab 17.0, this attribute returns an empty string. The ipAddress attribute can be found inside the respective runner manager. It is only available through the GraphQL CiRunnerManager type.

Example response:

[
    {
        "active": true,
        "paused": false,
        "description": "test-1-20150125",
        "id": 6,
        "ip_address": "",
        "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": "",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline"
    }
]

List all runners

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed, GitLab Dedicated

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

Prerequisites:

  • You must be an administrator of or have the Owner role for the target namespace or project.
  • For instance_type, you must be an administrator of the GitLab instance.
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
Attribute Type Required Description
scope string no Deprecated: 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
type string no The type of runners to return, one of: instance_type, group_type, project_type
status string no The status of runners to return, one of: online, offline, stale, or never_contacted.
Other possible values are the deprecated active and paused.
Requesting offline runners might also return stale runners because stale is included in offline.
paused boolean no Whether to include only runners that are accepting or ignoring new jobs
tag_list string array no A list of runner tags
version_prefix string no The prefix of the version of the runners to return. For example, 15.0, 16.1.241 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all"

The active and paused values in the status query parameter are deprecated and are scheduled for removal in a future version of the REST API. Use the paused query parameter instead.

The active attribute in the response is deprecated and is scheduled for removal in a future version of the REST API. Use the paused attribute instead.

The ip_address attribute in the response is deprecated in GitLab 16.1 and is scheduled for removal in a future version of the REST API. In GitLab 17.0, this attribute returns an empty string. The ipAddress attribute can be found inside the respective runner manager. It is only available through the GraphQL CiRunnerManager type.

Example response:

[
    {
        "active": true,
        "paused": false,
        "description": "shared-runner-1",
        "id": 1,
        "ip_address": "",
        "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": "",
        "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": "",
        "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": "",
        "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.

Instance runner details through this endpoint are available to all authenticated users.

Prerequisites:

  • You must have at least the Developer role for the target namespace or project.
  • An access token with the manage_runner scope and the appropriate role.
GET /runners/:id
Attribute Type Required Description
id integer yes The ID of a runner 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"

The active attribute in the response is deprecated and is scheduled for removal in a future version of the REST API. Use the paused attribute instead.

The ip_address attribute in the response is deprecated in GitLab 16.1 and is scheduled for removal in a future version of the REST API. In GitLab 17.0, this attribute returns an empty string. The ipAddress attribute can be found inside the respective runner manager. It is only available through the GraphQL CiRunnerManager type.

The version, revision, platform, and architecture attributes in the response are deprecated in GitLab 17.0 and are scheduled for removal in a future version of the REST API. The same attributes can be found inside the respective runner manager. It is only available through the GraphQL CiRunnerManager type.

Example response:

{
    "active": true,
    "paused": false,
    "architecture": null,
    "description": "test-1-20150125",
    "id": 6,
    "ip_address": "",
    "is_shared": false,
    "runner_type": "project_type",
    "contacted_at": "2016-01-25T16:39:48.066Z",
    "maintenance_note": null,
    "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.

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
```0

Prerequisites:

- For `instance_type`, you must be an administrator of the GitLab instance.
- For `group_type`, you must have the Owner role for the target namespace.
- For `project_type`, you must have at least the Maintainer role for the target project.
- An access token with the `manage_runner` scope and the appropriate role.

| Attribute          | Type    | Required | Description                                                                                     |
|--------------------|---------|----------|-------------------------------------------------------------------------------------------------|
| `id`               | integer | yes      | The ID of a runner                                                                              |
| `description`      | string  | no       | The description of the runner                                                                   |
| `active`           | boolean | no       | Deprecated: Use `paused` instead. Flag indicating whether the runner is allowed to receive jobs |
| `paused`           | boolean | no       | Specifies if the runner should ignore new jobs                                             |
| `tag_list`         | array   | no       | The list of tags for the runner                                                                 |
| `run_untagged`     | boolean | no       | Specifies if the runner can execute untagged jobs                                          |
| `locked`           | boolean | no       | Specifies if the runner is locked                                                          |
| `access_level`     | string  | no       | The access level of the runner; `not_protected` or `ref_protected`                              |
| `maximum_timeout`  | integer | no       | Maximum timeout that limits the amount of time (in seconds) that runners can run jobs           |
| `maintenance_note` | string  | no       | Free-form maintenance notes for the runner (1024 characters)                                    |

```plaintext
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
```1

The `active` query parameter is deprecated
and is scheduled for removal in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
Use the `paused` attribute instead.

The `ip_address` attribute in the response is deprecated
[in GitLab 16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/415159) and is scheduled for removal in
[a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
In GitLab 17.0, this attribute returns an empty string.
The `ipAddress` attribute can be found inside the respective runner manager.
It is only available through the GraphQL
[`CiRunnerManager` type](graphql/reference/_index.md#cirunnermanager).

Example response:

```plaintext
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
```2

### Pause a runner

Pause a runner.

Prerequisites:

- For `instance_type`, you must be an administrator of the GitLab instance.
- For `group_type`, you must have the Owner role for the target namespace.
- For `project_type`, you must have at least the Maintainer role for the target project.
- An access token with the `manage_runner` scope and the appropriate role.

```plaintext
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
```3

| Attribute   | Type    | Required | Description         |
|-------------|---------|----------|---------------------|
| `runner_id` | integer | yes      | The ID of a runner  |

```plaintext
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
```4

The `active` form attribute is deprecated
and is scheduled for removal in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
Use the `paused` attribute instead.

## List jobs processed by a runner

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.

```plaintext
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
```5

| Attribute   | Type    | Required | Description         |
|-------------|---------|----------|---------------------|
| `id`        | integer | yes      | The ID of a runner  |
| `system_id` | string  | no       | System ID of the machine where the runner manager is running |
| `status`    | string  | no       | Status of the job; one of: `running`, `success`, `failed`, `canceled` |
| `order_by`  | string  | no       | Order jobs by `id` |
| `sort`      | string  | no       | Sort jobs in `asc` or `desc` order (default: `desc`). If `sort` is specified, `order_by` must be specified as well |

```plaintext
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
```6

Example response:

```plaintext
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
```7

## List runner's managers

List all the managers of a runner.

```plaintext
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
```8

| Attribute | Type    | Required | Description         |
|-----------|---------|----------|---------------------|
| `id`      | integer | yes      | The ID of a runner  |

```plaintext
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
```9

Example response:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"
```0

## List project's runners

List all runners available in the project, including from ancestor groups and [any allowed instance runners](../ci/runners/runners_scope.md#enable-instance-runners-for-a-project).

Prerequisites:

- You must be an administrator of or have at least the Maintainer role for the target project.

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"
```1

| Attribute        | Type           | Required | Description                                                                                                                                                                                                          |
|------------------|----------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id`             | integer/string | yes      | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths)                                                                                                  |
| `scope`          | string         | no       | Deprecated: Use `type` or `status` instead. The scope of runners to return, one of: `active`, `paused`, `online` and `offline`; showing all runners if none provided                                                 |
| `type`           | string         | no       | The type of runners to return, one of: `instance_type`, `group_type`, `project_type`                                                                                                                                 |
| `status`         | string         | no       | The status of runners to return, one of: `online`, `offline`, `stale`, or `never_contacted`.<br/>Other possible values are the deprecated `active` and `paused`.<br/>Requesting `offline` runners might also return `stale` runners because `stale` is included in `offline`. |
| `paused`         | boolean        | no       | Whether to include only runners that are accepting or ignoring new jobs                                                                                                                                              |
| `tag_list`       | string array   | no       | A list of runner tags                                                                                                                                                                                                |
| `version_prefix` | string         | no       | The prefix of the version of the runners to return. For example, `15.0`, `14`, `16.1.241`                                                                                                                            |

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"
```2

The `active` and `paused` values in the `status` query parameter are deprecated
and are scheduled for removal in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
Use the `paused` query parameter instead.

The `active` attribute in the response is deprecated
and is scheduled for removal in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
Use the `paused` attribute instead.

The `ip_address` attribute in the response is deprecated
[in GitLab 16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/415159) and is scheduled for removal in
[a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
In GitLab 17.0, this attribute returns an empty string in GitLab 17.0.
The `ipAddress` attribute can be found inside the respective runner manager.
It is only available through the GraphQL
[`CiRunnerManager` type](graphql/reference/_index.md#cirunnermanager).

Example response:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"
```3

## Assign a runner to project

Assign an available project runner to the project.

Prerequisites:

- For `instance_type`, you must be an administrator of the GitLab instance.
- For `group_type`, you must have the Owner role for the target namespace.
- For `project_type`, you must have at least the Maintainer role for the target project.

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"
```4

| Attribute   | Type    | Required | Description         |
|-------------|---------|----------|---------------------|
| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths) |
| `runner_id` | integer | yes      | The ID of a runner  |

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"
```5

The `ip_address` attribute in the response is deprecated
[in GitLab 16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/415159) and is scheduled for removal in
[a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
In GitLab 17.0, this attribute returns an empty string.
The `ipAddress` attribute can be found inside the respective runner manager. It is only available through the GraphQL
[`CiRunnerManager` type](graphql/reference/_index.md#cirunnermanager).

Example response:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"
```6

## Unassign a runner from project

Unassign a project runner from the project.
You cannot unassign a runner from the owner project. If you attempt this action, an error occurs.
Use the call to [delete a runner](#delete-a-runner) instead.

Prerequisites:

- For `instance_type`, you must be an administrator of the GitLab instance.
- For `group_type`, you must have the Owner role for the target namespace.
- For `project_type`, you must have at least the Maintainer role for the target project.

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"
```7

| Attribute   | Type    | Required | Description         |
|-------------|---------|----------|---------------------|
| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths) |
| `runner_id` | integer | yes      | The ID of a runner  |

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"
```8

## List group's runners

List all runners available in the group and its ancestor groups, including [any allowed instance runners](../ci/runners/runners_scope.md#enable-instance-runners-for-a-group).

Prerequisites:

- You must be an administrator or have the Maintainer role for the target namespace.

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"
```9

| Attribute        | Type           | Required | Description                                                                                                                                                                                                             |
|------------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id`             | integer        | yes      | The ID of the group                                                                                                                                                                     |
| `type`           | string         | no       | The type of runners to return, one of: `instance_type`, `group_type`, `project_type`. The `project_type` value is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/351466) and is scheduled for removal in GitLab 15.0 |
| `status`         | string         | no       | The status of runners to return, one of: `online`, `offline`, `stale`, or `never_contacted`.<br/>Other possible values are the deprecated `active` and `paused`.<br/>Requesting `offline` runners might also return `stale` runners because `stale` is included in `offline`. |
| `paused`         | boolean        | no       | Whether to include only runners that are accepting or ignoring new jobs                                                                                                                                                 |
| `tag_list`       | string array   | no       | A list of runner tags                                                                                                                                                                                                   |
| `version_prefix` | string         | no       | The prefix of the version of the runners to return. For example, `15.0`, `14`, `16.1.241`                                                                                                                               |

```json
[
    {
        "active": true,
        "paused": false,
        "description": "test-1-20150125",
        "id": 6,
        "ip_address": "",
        "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": "",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline"
    }
]
```0

The `active` and `paused` values in the `status` query parameter are deprecated
and are scheduled for removal in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
Use the `paused` query parameter instead.

The `active` attribute in the response is deprecated
and is scheduled for removal in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
Use the `paused` attribute instead.

The `ip_address` attribute in the response is deprecated
[in GitLab 16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/415159) and is scheduled for removal in
[a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
In GitLab, t attribute returns an empty string.
The `ipAddress` attribute can be found inside the respective runner manager. It is only available through the GraphQL
[`CiRunnerManager` type](graphql/reference/_index.md#cirunnermanager).

Example response:

```json
[
    {
        "active": true,
        "paused": false,
        "description": "test-1-20150125",
        "id": 6,
        "ip_address": "",
        "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": "",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline"
    }
]
```1

## Create a runner

This endpoint returns an `HTTP 410 Gone` status code if registration with runner registration tokens
is disabled in the project or group settings. If registration with runner registration tokens
is disabled, use the [`POST /user/runners`](users.md#create-a-runner-linked-to-a-user) endpoint
to create and register runners instead.

Create a runner with a runner registration token.

```json
[
    {
        "active": true,
        "paused": false,
        "description": "test-1-20150125",
        "id": 6,
        "ip_address": "",
        "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": "",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline"
    }
]
```2

| Attribute          | Type         | Required | Description                                                                                                                                                                                    |
|--------------------|--------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `token`            | string       | yes      | [Registration token](#registration-and-authentication-tokens)                                                                                                                                  |
| `description`      | string       | no       | Description of the runner                                                                                                                                                                      |
| `info`             | hash         | no       | Runner'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 |
| `active`           | boolean      | no       | Deprecated: Use `paused` instead. Specifies if the runner is allowed to receive new jobs                                                                                                       |
| `paused`           | boolean      | no       | Specifies if the runner should ignore new jobs                                                                                                                                                 |
| `locked`           | boolean      | no       | Specifies if the runner should be locked for the current project                                                                                                                               |
| `run_untagged`     | boolean      | no       | Specifies if the runner should handle untagged jobs                                                                                                                                            |
| `tag_list`         | string array | no       | A list of runner tags                                                                                                                                                                          |
| `access_level`     | string       | no       | The access level of the runner; `not_protected` or `ref_protected`                                                                                                                             |
| `maximum_timeout`  | integer      | no       | Maximum timeout that limits the amount of time (in seconds) that runners can run jobs                                                                                                          |
| `maintainer_note`  | string       | no       | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/350730), see `maintenance_note`                                                                                                     |
| `maintenance_note` | string       | no       | Free-form maintenance notes for the runner (1024 characters)                                                                                                                                   |

```json
[
    {
        "active": true,
        "paused": false,
        "description": "test-1-20150125",
        "id": 6,
        "ip_address": "",
        "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": "",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline"
    }
]
```3

Response:

| Status    | Description                       |
|-----------|-----------------------------------|
| 201       | Runner was created                |
| 403       | Invalid runner registration token |
| 410       | Runner registration disabled      |

Example response:

```json
[
    {
        "active": true,
        "paused": false,
        "description": "test-1-20150125",
        "id": 6,
        "ip_address": "",
        "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": "",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline"
    }
]
```4

## Delete a runner

You can delete a runner by specifying the:

- Runner ID
- Runner's authentication token

### Delete a runner by ID

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

Prerequisites:

- For `instance_type`, you must be an administrator of the GitLab instance.
- For `group_type`, you must have the Owner role for the target namespace.
- For `project_type`, you must have at least the Maintainer role for the target project.
- An access token with the `manage_runner` scope and the appropriate role.

```json
[
    {
        "active": true,
        "paused": false,
        "description": "test-1-20150125",
        "id": 6,
        "ip_address": "",
        "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": "",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline"
    }
]
```5

| Attribute   | Type    | Required | Description         |
|-------------|---------|----------|---------------------|
| `id`        | integer | yes      | The ID of a runner. The ID is visible in the UI under **Settings > CI/CD**. Expand **Runners**, and below **Remove Runner** is an ID preceded by the pound sign, for example, `#6`. |

```json
[
    {
        "active": true,
        "paused": false,
        "description": "test-1-20150125",
        "id": 6,
        "ip_address": "",
        "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": "",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline"
    }
]
```6

### Delete a runner by authentication token

To delete the runner by using its authentication token:

Prerequisites:

- You must be an administrator of or have the Owner role for the target namespace or project.
- For `instance_type`, you must be an administrator of the GitLab instance.

```json
[
    {
        "active": true,
        "paused": false,
        "description": "test-1-20150125",
        "id": 6,
        "ip_address": "",
        "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": "",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline"
    }
]
```7

| Attribute   | Type    | Required | Description         |
|-------------|---------|----------|---------------------|
| `token`     | string  | yes      | The runner's [authentication token](#registration-and-authentication-tokens). |

```json
[
    {
        "active": true,
        "paused": false,
        "description": "test-1-20150125",
        "id": 6,
        "ip_address": "",
        "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": "",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline"
    }
]
```8

Response:

| Status    | Description                     |
|-----------|---------------------------------|
| 204       | Runner was deleted              |

## Verify authentication for a registered runner

Validates authentication credentials for a registered runner.

```json
[
    {
        "active": true,
        "paused": false,
        "description": "test-1-20150125",
        "id": 6,
        "ip_address": "",
        "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": "",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline"
    }
]
```9

| Attribute   | Type    | Required | Description                                                                                    |
|-------------|---------|----------|------------------------------------------------------------------------------------------------|
| `token`     | string  | yes      | The runner's [authentication token](#registration-and-authentication-tokens).                  |
| `system_id` | string  | no       | The runner's system identifier. This attribute is required if the `token` starts with `glrt-`. |

```plaintext
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
```0

Response:

| Status    | Description                     |
|-----------|---------------------------------|
| 200       | Credentials are valid           |
| 403       | Credentials are invalid         |

Example response:

```plaintext
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
```1

## Reset instance's runner registration token

Runner registration tokens and support for certain configuration arguments were [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6. These features are scheduled for removal in GitLab 17.0.
After GitLab 17.0, you can no longer reset runner registration tokens and the `reset_registration_token` endpoint cannot function.

Reset the runner registration token for the GitLab instance.

```plaintext
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
```2

```plaintext
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
```3

## Reset project's runner registration token

Runner registration tokens and support for certain configuration arguments were [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6. These features scheduled for removal in GitLab 17.0.
After GitLab 17.0, you can no longer reset runner registration tokens and the `reset_registration_token` endpoint cannot function.

Reset the runner registration token for a project.

```plaintext
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
```4

```plaintext
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
```5

## Reset group's runner registration token

Runner registration tokens and support for certain configuration arguments were [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6. These features are scheduled for removal in GitLab 17.0.
After GitLab 17.0, you can no longer reset runner registration tokens and the `reset_registration_token` endpoint cannot function.

Reset the runner registration token for a group.

```plaintext
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
```6

```plaintext
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
```7

## Reset runner's authentication token by using the runner ID

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

Prerequisites:

- For `instance_type`, you must be an administrator of the GitLab instance.
- For `group_type`, you must have the Owner role for the target namespace.
- For `project_type`, you must have at least the Maintainer role for the target project.
- An access token with the `manage_runner` scope and the appropriate role.

```plaintext
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
```8

| Attribute | Type    | Required | Description         |
|-----------|---------|----------|---------------------|
| `id`      | integer | yes      | The ID of a runner  |

```plaintext
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
```9

Example response:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all"
```0

## 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.

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all"
```1

| Attribute | Type    | Required | Description                            |
|-----------|---------|----------|----------------------------------------|
| `token`   | string  | yes      | The authentication token of the runner |

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all"
```2

Example response:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all"
```3