Runner State History

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.

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

Path parameters

ownerstring required

Username of the app owner

Example:user_123

Username of the app owner

namestring required

Application name

Example:my-app

Application name

Query parameters

string date-time

string

Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.

string date-time

string

End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time.

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

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).

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

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

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

No recorded changes to this endpoint across all 2 revisions of this API.