Runners API
Monitor runner status and availability. List runners and check their connected Pods through the REST API.
Endpoints
| Method | Path | Scope | Description |
|---|---|---|---|
GET | /runners | runners:read | List all runners |
GET | /runners/:id | runners:read | Get runner details |
GET | /runners/available | runners:read | List available (online) runners |
GET | /runners/:id/pods | runners:read | List pods on a runner |
Endpoint Details
GET /runners
Retrieve a list of all runners registered in the organization.
Response Example
{
"runners": [
{
"id": 1,
"name": "dev-runner-01",
"status": "online",
"version": "1.2.0",
"os": "linux",
"arch": "amd64",
"labels": ["gpu", "high-memory"],
"pod_count": 3,
"max_pods": 10,
"last_heartbeat_at": "2025-01-15T14:30:00Z",
"created_at": "2025-01-01T00:00:00Z"
}
]
}GET /runners/:id
Retrieve detailed information about a specific runner.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer | Required | The numeric ID of the runner |
Response Example
{
"runner": {
"id": 1,
"name": "dev-runner-01",
"status": "online",
"version": "1.2.0",
"os": "linux",
"arch": "amd64",
"labels": ["gpu", "high-memory"],
"pod_count": 3,
"max_pods": 10,
"last_heartbeat_at": "2025-01-15T14:30:00Z",
"created_at": "2025-01-01T00:00:00Z"
}
}GET /runners/available
Retrieve a list of runners that are currently online and available to accept new pods.
Response Example
{
"runners": [
{
"id": 1,
"name": "dev-runner-01",
"status": "online",
"version": "1.2.0",
"os": "linux",
"arch": "amd64",
"labels": ["gpu", "high-memory"],
"pod_count": 3,
"max_pods": 10,
"last_heartbeat_at": "2025-01-15T14:30:00Z",
"created_at": "2025-01-01T00:00:00Z"
}
]
}GET /runners/:id/pods
Retrieve a paginated list of pods running on a specific runner.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer | Required | The numeric ID of the runner |
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| status | string | Optional | - | Filter by pod status (e.g., running, terminated) |
| limit | integer | Optional | 50 | Maximum number of results to return |
| offset | integer | Optional | 0 | Number of results to skip for pagination |
Response Example
{
"pods": [
{
"key": "pod-abc123",
"status": "running",
"agent_type_id": "claude-code",
"initial_prompt": "Fix the login bug",
"created_at": "2025-01-15T10:30:00Z"
}
],
"total": 8,
"limit": 50,
"offset": 0
}