CircleCI’s self-hosted runner API
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 |
HTTP Basic auth username |
The token can be provided using the Basic scheme, where username should be set as the |
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.
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
-
Examples
curl -X GET https://runner.circleci.com/api/v3/runner?resource-class=test-namespace/test-resource \ -H "Circle-Token: secret-token"
curl -X GET https://runner.circleci.com/api/v3/runner?namespace=test-namespace \ -H "Circle-Token: secret-token"
Response schema
Name | Type | Required | Description |
---|---|---|---|
|
[object] |
true |
array containing the self-hosted runners |
|
string |
true |
self-hosted runner resource class |
|
string |
true |
self-hosted runner hostname |
|
string |
true |
self-hosted runner name |
|
string (date-time) |
true |
first time the self-hosted runner was connected |
|
string (date-time) |
true |
last time the self-hosted runner was connected |
|
string (date-time) |
true |
last time the self-hosted runner was used to run a job |
|
string |
true |
version of the machine runner launch-agent running |
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 |
---|---|---|---|---|
|
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"
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 |
---|---|---|---|---|
|
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"