Documentation structure for LLMs (llms.txt)
CircleCI Logo

Monitor self-hosted runner fleets Preview

1 day ago
Cloud

Introduction

A fleet is the set of runner agents attached to one resource class. Use fleet data to see the number of connected agents, whether they are busy, and the number of tasks waiting for an agent. This helps you decide when to add capacity or investigate agents that have gone offline.

You can view fleets with the CircleCI CLI or with the API v3 fleet endpoints. A fleet shares the ID of its resource class, so you can use either the namespace/name of a resource class or its ID to identify a fleet.

Fleet visibility is in preview. The API v3 fleet endpoints are experimental, and the CLI commands that use them inherit that status. Field names, response shapes, and pagination may change without notice.

What you can see about a fleet

For every fleet, you can see the following information:

Data Description

Active agents

The number of agents that are currently running a task.

Idle agents

The number of agents that have connected and are waiting for a task.

Disconnected agents

The number of agents that have stopped reporting to CircleCI.

Total agents

The total number of agents in the fleet.

Running tasks

The number of tasks that agents in the fleet are running.

Queued tasks

The number of tasks that are waiting for an agent.

Last task claimed

The time an agent in the fleet last claimed a task. The value is never if no agent has claimed a task.

The circleci runner fleet get command and the API also show the agents attached to the fleet, with their names and IDs.

The total agent count includes agents seen in the last 7 days. The active, idle, and disconnected counts leave out agents that have been silent for 10 minutes or more. A fleet can show a total of four agents with all three state counts at zero.

View fleets with the CLI

The circleci runner fleet commands wrap the API v3 fleet endpoints. Refer to The CircleCI CLI for how to install and authenticate the CLI.

List fleets

Use circleci runner fleet list to list fleets. Filter the list by one of the following. You can use only one filter at a time.

  • --org: An organization slug, such as gh/my-org, or an organization ID. If you do not set a filter, the CLI uses the organization from your git remote.

  • --namespace: A resource class namespace.

  • --resource-class: A single resource class, as namespace/name or an ID.

The command has the alias circleci runner fleet ls.

$ circleci runner fleet list --namespace <my-namespace>

The output is a table with one row for each fleet, including running and queued task counts. The --json output includes the same counts as running_tasks and queued_tasks.

Resource Class      | Active | Idle | Disconnected | Agents | Running | Queued | Last Task Claimed
my-org/linux-runner | 2      | 1    | 1            | 4      | 2       | 5      | 2026-04-18T12:00:00Z
my-org/arm-runner   | 0      | 0    | 0            | 0      | 0       | 0      | never

Get a fleet

Use circleci runner fleet get <resource-class> to view one fleet. Pass the resource class as namespace/name or as its ID.

$ circleci runner fleet get <my-namespace>/<my-resource-class>

Along with the data returned by list, this command shows the agents attached to the fleet.

Resource Class: my-org/linux-runner
ID: 11111111-1111-4111-8111-111111111111
Active: 2
Idle: 1
Disconnected: 1
Agents: 4
Running Tasks: 2
Queued Tasks: 5
Last Task Claimed: 2026-04-18T12:00:00Z

Agent    | ID
runner-1 | aaaaaaaa-1111-4111-8111-aaaaaaaaaaaa
runner-2 | aaaaaaaa-2222-4222-8222-aaaaaaaaaaaa
runner-3 | aaaaaaaa-3333-4333-8333-aaaaaaaaaaaa
runner-4 | aaaaaaaa-4444-4444-8444-aaaaaaaaaaaa

If a fleet has more agents than the response includes, the command displays a message. Run circleci runner instance list to see every agent for the resource class.

Script with JSON output

Both commands support the --json and --jq flags, so you can use them in scripts. Run circleci runner fleet list --help or circleci runner fleet get --help to see the JSON fields for each command.

Find the resource classes that have no connected agents.

$ circleci runner fleet list --json --jq '.[] | select(.active_agents + .idle_agents == 0) | .resource_class'

Find fleets that have tasks waiting for an agent.

$ circleci runner fleet list --namespace <my-namespace> --json --jq '.[] | select(.queued_tasks > 0) | .resource_class'

Find fleets that have no idle agents.

$ circleci runner fleet list --namespace <my-namespace> --json --jq '.[] | select(.idle_agents == 0) | .resource_class'

View fleets with the API

For the endpoints, parameters, and response schemas, refer to the Runner Fleets section of the API v3 reference.

List and filter responses from GET /api/v3/runner/fleets include running_tasks, queued_tasks, and the attached agents for each fleet. To get one fleet, use GET /api/v3/runner/fleets/:id, where :id is the ID of the resource class.

Next steps