Skip to content
Docs
Cancel

CircleCI Self-hosted Runner API

Last updated
Tags Cloud Server v3.x

Authentication Methods

The CircleCI 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.

Launch token

This token is the same one used in the launch-agent setup.

Supported methods

Name Description

http bearer auth

The token that should be provided using the Bearer scheme.

Endpoints

GET /api/v2/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/v2/runner for users that have already logged into circleci.com.

  • Launch Token

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/v2/runner?resource-class=test-namespace/test-resource \
    -H 'Circle-Token: secret-token'
curl -X GET https://runner.circleci.com/api/v2/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 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/v2/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/v2/runner for users that have already logged into circleci.com.

  • Launch Token

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/v2/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/v2/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/v2/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/v2/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.

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.

6,000 Minutes Free

CircleCI, now with more build minutes
than anyone else for FREE 🎉

Sign up for Free

These teams get it

CCI customer teams