Skip to main content
GET
/
v1
/
runner
List Runners
curl --request GET \
  --url https://api.comfycontrol.app/v1/runner \
  --header 'Authorization: Bearer <token>'
{
  "401": {},
  "runners": [
    {}
  ],
  "total": 123,
  "runners[].id": "<string>",
  "runners[].user_id": "<string>",
  "runners[].name": "<string>",
  "runners[].status": "<string>",
  "runners[].endpoint": "<string>",
  "runners[].tags": [
    "<string>"
  ],
  "runners[].headers": {},
  "runners[].created_at": "<string>",
  "runners[].updated_at": "<string>"
}

​
Overview

Retrieve all runners registered to your account with pagination support. Results are ordered by creation date (newest first).

​
Query Parameters

​
page
integer
Page number to retrieve (default: 1, minimum: 1).
​
per_page
integer
Number of runners per page (default: 10, minimum: 1, maximum: 100).
​
status
string
Filter runners by status (possible values: “active”, “disabled”)

​
Response

​
runners
array
required
Array of runner objects.
​
total
integer
required
Total number of runners across all pages.

​
Runner Object

​
runners[].id
string
required
Unique identifier (UUID) for the runner.
​
runners[].user_id
string
required
UUID of the user who owns this runner.
​
runners[].name
string
required
The runner’s name.
​
runners[].status
string
required
Current status of the runner. Values: active, disabled
​
runners[].endpoint
string
required
The URL where the runner is accessible.
​
runners[].tags
string[]
required
Array of tags associated with the runner.
​
runners[].headers
object
required
Custom headers configured for this runner.
​
runners[].created_at
string
required
ISO 8601 timestamp when the runner was created.
​
runners[].updated_at
string
required
ISO 8601 timestamp when the runner was last updated.

​
Example Response

{
  "runners": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Production GPU Runner",
      "status": "active",
      "endpoint": "https://my-comfy.example.com",
      "tags": ["production", "gpu-a100"],
      "headers": {
        "Authorization": "Bearer secret_token"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Development Runner",
      "status": "active",
      "endpoint": "http://192.168.1.100:8188",
      "tags": ["development", "cpu"],
      "headers": {},
      "created_at": "2024-01-14T08:20:00Z",
      "updated_at": "2024-01-14T08:20:00Z"
    }
  ],
  "total": 2
}

​
Error Responses

​
401
error
Unauthorized - invalid or missing authentication token.

​
Notes

  • Results are ordered by creation date (newest first)
  • The total field indicates the total count across all pages