Skip to main content
GET
/
runners
/
{runner_id}
curl -X GET https://rest.alpha.fal.ai/runners/abc123-def456-ghi789 \
  -H "Authorization: Key $FAL_KEY"

{
  "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
    }
  ]
}

curl -X GET https://rest.alpha.fal.ai/runners/abc123-def456-ghi789 \
  -H "Authorization: Key $FAL_KEY"
Path Parameters:
​
runner_id
string
required
ID of the runner
{
  "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:
StateDescription
RUNNINGRunner is active and processing requests
PENDINGRunner is waiting to be scheduled
SETUPRunner is initializing and loading the model
DEADRunner 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.
⌘I