FAfal
Serverless
Apps

Runner State History

Changed on

Returns historical runner counts by state (running, idle, pending, draining) for an application, bucketed over time.

Use cases:

  • Capacity/utilization analysis: compare idle vs running over days or weeks to see how much reserved capacity goes unused (use aggregation=avg)
  • Incident forensics: correlate error spikes with runner drops or drain events around the incident window (use aggregation=max)

Time range: up to 90 days of history. Defaults to the last 24 hours when start/end are omitted. Bucket size is auto-detected from the range unless timeframe is specified.

Authentication: Required via API key. Only the app owner can query it.

Required permissions: serverless:apps:read. Key presets that include them: SERVERLESS, DEPLOY, READONLY, FULL. See key permissions.

get/serverless/apps/{owner}/{name}/runners/history

Request

  • Base URL
    https://api.fal.ai/v1
  • URL
    https://api.fal.ai/v1/serverless/apps/{owner}/{name}/runners/history
  • Auth
    API key in header Authorization

Path parameters

ownerstring required

Username of the app owner

Example:user_123
namestring required

Application name

Example:my-app

Query parameters

string date-time
OR
string
string date-time
OR
string
timeframe'minute' | 'hour' | 'day' | 'week' | 'month'

Bucket size for the time series (auto-detected from the date range if not specified). Auto-detection uses: minute (<2h), hour (<2d), day (<64d), week (<183d), month (>=183d).

Example:day
aggregation'max' | 'avg'

How runner counts are aggregated within each bucket: 'max' shows peak concurrency (capacity analysis), 'avg' shows mean concurrency (utilization analysis).

Example:max

Response

Successfully retrieved runner state history

endpoint_idstring required

Canonical endpoint identifier ('<owner>/<name>')

timeframe'minute' | 'hour' | 'day' | 'week' | 'month' required

Bucket size used for the series (resolved if auto-detected)

aggregation'max' | 'avg' required

Aggregation applied within each bucket

Example response

{
  "endpoint_id": "user_123/my-app",
  "timeframe": "day",
  "aggregation": "max",
  "history": [
    {
      "timestamp": "2026-07-01T12:00:00Z",
      "running": 2,
      "idle": 1
    }
  ]
}

Changes

  • 479db2f9dcd6Revision changes
    • info

      the endpoint scheme security readonlyApiKey was added to the API

    • info

      the endpoint scheme security apiKey was removed from the API