Runners REST API

The Runners REST API allows you to monitor and manage the runners that execute your fal applications.

Endpoints Overview

Endpoint	Method	Description
`/runners/`	GET	List all runners with optional filtering
`/runners/{runner_id}`	GET	Get detailed information about a runner

Authentication

All requests require authentication using your fal API key:

Authorization: Key $FAL_KEY

List Runners

Retrieve a list of your runners, including both active and recently finished ones.

GET /runners/

Query Parameters

Parameter	Type	Required	Description
`start_time`	datetime	No	Include runners that were active after this time
`end_time`	datetime	No	Include runners that were active before this time
`application`	string	No	Filter by application name (case-insensitive)

Example Request

curl -X GET "https://rest.alpha.fal.ai/runners/?application=my-app" \
  -H "Authorization: Key $FAL_KEY"

Response

Returns a list of runner objects:

{
  "runners": [
    {
      "runner_id": "b9a2835f-12c7-48d1-b48a-50064218cb0c",
      "application": "test-long-startup-app",
      "state": "RUNNING",
      "machine_type": "S",
      "region": "us-east",
      "node_id": "fcf7db39-7326-3cdf-103c-8191fd345745",
      "started_at": "2025-09-18T18:05:42+00:00",
      "finished_at": null,
      "owner": "github|5367102",
      "cpu_usage_percent": null,
      "memory_usage_bytes": null,
      "vram_usage_ratio": null
    },
    {
      "runner_id": "41512b2d-d821-4d62-a98b-9472c9d43941",
      "application": "test-startup-timeout",
      "state": "dead",
      "machine_type": "S",
      "region": "",
      "node_id": "",
      "started_at": "2025-09-19T12:05:40.729467+00:00",
      "finished_at": "2025-09-19T12:16:11.238922+00:00",
      "owner": "github|5367102",
      "cpu_usage_percent": null,
      "memory_usage_bytes": null,
      "vram_usage_ratio": null
    },
    {
      "runner_id": "e0a4c199-863c-481e-9a7e-008391e079b9",
      "application": "test-startup-timeout",
      "state": "PENDING",
      "machine_type": "S",
      "region": "pending",
      "node_id": "pending",
      "started_at": null,
      "finished_at": null,
      "owner": "github|5367102",
      "cpu_usage_percent": null,
      "memory_usage_bytes": null,
      "vram_usage_ratio": null
    }
  ]
}

Get Runner Details

Retrieve detailed information about a specific runner, including resource usage history.

GET /runners/{runner_id}

Path Parameters

Parameter	Type	Required	Description
`runner_id`	string	Yes	ID of the runner

Example Request

curl -X GET https://rest.alpha.fal.ai/runners/abc123-def456-ghi789 \
  -H "Authorization: Key $FAL_KEY"

Response

Returns detailed runner information with usage history:

{
  "runner_id": "abc123-def456-ghi789",
  "application": "my-text-to-image-app",
  "state": "RUNNING",
  "machine_type": "GPU-T4",
  "region": "us-west",
  "node_id": "node-xyz789",
  "started_at": "2024-01-15T10:30:00Z",
  "finished_at": null,
  "owner": "user123",
  "cpu_usage_history": [
    {
      "datetime": "2024-01-15T10:30:00Z",
      "cpu_usage_percent": 20.5
    },
    {
      "datetime": "2024-01-15T10:30:15Z",
      "cpu_usage_percent": 45.2
    }
  ],
  "memory_usage_history": [
    {
      "datetime": "2024-01-15T10:30:00Z",
      "memory_usage_bytes": 1073741824
    },
    {
      "datetime": "2024-01-15T10:30:15Z",
      "memory_usage_bytes": 2147483648
    }
  ],
  "vram_usage_history": [
    {
      "datetime": "2024-01-15T10:30:00Z",
      "vram_usage_ratio": 0.5
    },
    {
      "datetime": "2024-01-15T10:30:15Z",
      "vram_usage_ratio": 0.75
    }
  ]
}

Runner States

Runners can have the following states:

State	Description
`RUNNING`	Runner is active and processing requests
`PENDING`	Runner is waiting to be scheduled
`SETUP`	Runner is initializing and loading the model
`DEAD`	Runner has finished and is no longer active

Time-based Filtering

When using start_time and end_time parameters:

Times should be in ISO 8601 format (e.g., 2024-01-15T10:30:00Z)
Historical data is limited to the last 24 hours for performance reasons
If no time parameters are provided, only currently active runners are returned

Example with Time Filtering

curl -X GET "https://rest.alpha.fal.ai/runners/?start_time=2024-01-15T09:00:00Z&end_time=2024-01-15T11:00:00Z" \
  -H "Authorization: Key $FAL_KEY"

Resource Usage Metrics

The detailed runner endpoint provides resource usage history:

CPU Usage: Percentage of CPU utilization (0-100)
Memory Usage: Memory consumption in bytes
VRAM Usage: GPU memory utilization ratio (0.0-1.0)

Metrics are collected every 15 seconds while the runner is active.

Error Responses

Standard HTTP error responses:

404 Not Found

{
  "detail": "Runner abc123-def456-ghi789 not found"
}

422 Validation Error

{
  "detail": [
    {
      "loc": ["query", "start_time"],
      "msg": "invalid datetime format",
      "type": "value_error"
    }
  ]
}