CircleCI’s self-hosted runner API

Language Icon 24 days ago · 9 min read
Cloud Server v4+
Contribute Go to Code

This document contains all the external facing endpoints for the CircleCI’s self-hosted runner API. This API is separate from the main CircleCI v2 API and is used for the management and execution of self-hosted runner jobs. It is hosted at runner.circleci.com

Authentication methods

The CircleCI’s self-hosted runner API contains different authentication methods. Each authentication method may be used in different endpoints for different purposes. Also, one endpoint may accept multiple authentication methods.

Circle-Token (personal authentication)

This authentication method is based on personal tokens and follows the same rules for CircleCI v2 API.

Name Description

Circle-Token header

Header that contains the <circle-token> used to authenticate the user.

HTTP Basic auth username

The token can be provided using the Basic scheme, where username should be set as the <circle-token> and the password should be left blank.

Browser session authentication

Ring-session sent through a cookie on the request. This authentication allows users that are already logged into CircleCI.com to access certain endpoints seamlessly.

Resource class token authentication

This token is generated when creating a new resource class. This token is only displayed once when creating a resource class, and cannot be retrieved again. This token is used exclusively by the self-hosted runner agents for claiming tasks.

Supported methods

Name Description

HTTP Bearer auth

The token that should be provided using the Bearer scheme.

Endpoints

GET /api/v3/runner

Lists the available self-hosted runners based on the specified parameters. It is mandatory to use one parameter to filter results.

Authentication methods

  • Circle-Token (personal authentication)

  • Browser session authentication

    • This allows the endpoint to be accessible on circleci.com/api/v3/runner for users that have already logged into circleci.com

Request
Name Type Input Required Description

resource-class

string

query

false

filters the list of self-hosted runners by specific resource class.

namespace

string

query

false

filters the list of self-hosted runners by namespace.

Examples

curl -X GET https://runner.circleci.com/api/v3/runner?resource-class=test-namespace/test-resource \
-H "Circle-Token: secret-token"
shell
curl -X GET https://runner.circleci.com/api/v3/runner?namespace=test-namespace \
-H "Circle-Token: secret-token"
shell

Response

Status Description Format

200

List of agents

JSON

Response schema

Name Type Required Description

items

[object]

true

array containing the self-hosted runners

resource_class

string

true

self-hosted runner resource class

hostname

string

true

self-hosted runner hostname

name

string

true

self-hosted runner name

first_connected

string (date-time)

true

first time the self-hosted runner was connected

last_connected

string (date-time)

true

last time the self-hosted runner was connected

last_used

string (date-time)

true

last time the self-hosted runner was used to run a job

version

string

true

version of the machine runner launch-agent running

Example

{
"items": [
{
"resource_class": "test-namespace/test-resource",
"hostname": "bobby",
"name": "bobby-sue",
"first_connected": "2020-05-15T00:00:00Z",
"last_connected": "2020-05-16T00:00:00Z",
"last_used": "2020-05-17T00:00:00Z",
"version": "5.4.3.2.1"
}
]
}
json

GET /api/v3/runner/tasks

Get the number of unclaimed tasks for a given resource class.

Authentication methods

  • Circle-Token (personal authentication)

  • Browser session authentication

    • This allows the endpoint to be accessible on circleci.com/api/v3/runner for users that have already logged into circleci.com

Request

Name Type Input Required Description

resource-class

string

query

true

filters tasks by specific resource class.

Examples

curl -X GET https://runner.circleci.com/api/v3/runner/tasks?resource-class=test-namespace/test-resource \
-H "Circle-Token: secret-token"
shell

Response

Status Description Format

200

Number of unclaimed tasks

JSON

Response schema

Name Type Required Description

unclaimed_task_count

int

true

number of unclaimed tasks

Example

{
"unclaimed_task_count": 42
}
json

GET /api/v3/runner/tasks/running

Get the number of running tasks for a given resource class.

Authentication methods

  • Circle-Token (personal authentication)

  • Browser Session Authentication

    • This allows the endpoint to be accessible on circleci.com/api/v3/runner for users that have already logged into circleci.com.

Request

Name Type Input Required Description

resource-class

string

query

true

filters tasks by specific resource class.

Examples

curl -X GET https://runner.circleci.com/api/v3/runner/tasks/running?resource-class=test-namespace/test-resource \
-H "Circle-Token: secret-token"
shell

Response

Status Description Format

200

Number of running tasks

JSON

Response schema

Name Type Required Description

running_runner_tasks

int

true

number of running tasks

Example

{
"running_runner_tasks": 42
}
json