CircleCI’s self-hosted runner API
On This Page
- Authentication methods
- Circle-Token (personal authentication)
- Browser session authentication
- Resource class token authentication
- Supported methods
- Endpoints
- GET /api/v3/runner
- Authentication methods
- Request
- Examples
- Response
- Response schema
- Example
- GET /api/v3/runner/tasks
- Authentication methods
- Request
- Examples
- Response
- Response schema
- Example
- GET /api/v3/runner/tasks/running
- Authentication methods
- Request
- Examples
- Response
- Response schema
- Example
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.
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.
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
-
-
Resource class token (generated when creating a resource class)
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"
curl -X GET https://runner.circleci.com/api/v3/runner?namespace=test-namespace \
-H "Circle-Token: secret-token"
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"
}
]
}
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"
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
}
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"
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
}
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Need support?
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.