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.

Authorizations

http
oauth2

Parameters

Query Parameters

scope

string

nullable

Allowed values: specific shared instance_type group_type project_type active paused online offline never_contacted stale

Deprecated: Use type or status instead. The scope of runners to return

type

string

nullable

Allowed values: instance_type group_type project_type

The type of runners to return

paused

boolean

nullable

Whether to include only runners that are accepting or ignoring new jobs

status

string

nullable

Allowed values: active paused online offline never_contacted stale

The status of runners to return

tag_list

Array<string>

nullable

A list of runner tags

Example

?tag_list=macos,shell

version_prefix

string

nullable /(?<=^|\n(?!$))[\d+.]+/

The version prefix of runners to return

Example

15.1.

page

integer

default: 1 nullable

Current page number

Example

per_page

integer

default: 20 nullable

Number of items per page

Example

Responses

200

application/json

object

integer format: int64

description

string

ip_address

string

active

boolean

paused

boolean

is_shared

boolean

runner_type

string

name

string

online

boolean

created_by

object

integer format: int64

username

string

public_email

string

name

string

state

string

locked

boolean

avatar_url

string

avatar_path

string

custom_attributes

Array<object>

object

key

string

value

string

web_url

string

created_at

string format: date-time

status

string

job_execution_status

string

Example

{
  "id": 8,
  "description": "test-1-20150125",
  "ip_address": "127.0.0.1",
  "active": true,
  "paused": false,
  "is_shared": true,
  "runner_type": "instance_type",
  "name": "test",
  "online": true,
  "created_by": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "created_at": "2025-05-03T00:00:00.000Z",
  "status": "online",
  "job_execution_status": "idle"
}

400

Scope contains invalid value

401

Unauthorized