> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comfycontrol.app/llms.txt
> Use this file to discover all available pages before exploring further.

# List Runners

> Retrieve a paginated list of your runners

## Overview

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

## Query Parameters

<ParamField query="page" type="integer">
  Page number to retrieve (default: 1, minimum: 1).
</ParamField>

<ParamField query="per_page" type="integer">
  Number of runners per page (default: 10, minimum: 1, maximum: 100).
</ParamField>

<ParamField query="status" type="string">
  Filter runners by status (possible values: "active", "disabled")
</ParamField>

## Response

<ResponseField name="runners" type="array" required>
  Array of runner objects.
</ResponseField>

<ResponseField name="total" type="integer" required>
  Total number of runners across all pages.
</ResponseField>

### Runner Object

<ResponseField name="runners[].id" type="string" required>
  Unique identifier (UUID) for the runner.
</ResponseField>

<ResponseField name="runners[].user_id" type="string" required>
  UUID of the user who owns this runner.
</ResponseField>

<ResponseField name="runners[].name" type="string" required>
  The runner's name.
</ResponseField>

<ResponseField name="runners[].status" type="string" required>
  Current status of the runner. Values: `active`, `disabled`
</ResponseField>

<ResponseField name="runners[].endpoint" type="string" required>
  The URL where the runner is accessible.
</ResponseField>

<ResponseField name="runners[].tags" type="string[]" required>
  Array of tags associated with the runner.
</ResponseField>

<ResponseField name="runners[].headers" type="object" required>
  Custom headers configured for this runner.
</ResponseField>

<ResponseField name="runners[].created_at" type="string" required>
  ISO 8601 timestamp when the runner was created.
</ResponseField>

<ResponseField name="runners[].updated_at" type="string" required>
  ISO 8601 timestamp when the runner was last updated.
</ResponseField>

## Example Response

```json theme={null}
{
  "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

<ResponseField name="401" type="error">
  Unauthorized - invalid or missing authentication token.
</ResponseField>

## Notes

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