Docs
Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

CircleCI’s self-hosted runner API

1 month ago2 min read
Cloud
Server v4.x
Server v3.x
On This Page

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.

NameDescription

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.

Supported methods

NameDescription

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
NameTypeInputRequiredDescription

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

StatusDescriptionFormat

200

List of agents

JSON

Response schema

NameTypeRequiredDescription

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

NameTypeInputRequiredDescription

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

StatusDescriptionFormat

200

Number of unclaimed tasks

JSON

Response schema

NameTypeRequiredDescription

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

NameTypeInputRequiredDescription

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

StatusDescriptionFormat

200

Number of running tasks

JSON

Response schema

NameTypeRequiredDescription

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.

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.

Creative Commons License

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.