Cloud Runners API | FlightStack

Cloud Runners API

Cloud runners are on-demand build VMs FlightStack provisions when your self-hosted agents are saturated (or absent). All endpoints are scoped to an organization and live under /organizations/{orgId}/cloud-runners.

Configuration

Method	Path	Purpose
GET	`/organizations/{orgId}/cloud-runners/config`	Get cloud-runner config.
PUT	`/organizations/{orgId}/cloud-runners/config`	Update config (image, machine type, max concurrency, budget).
POST	`/organizations/{orgId}/cloud-runners/enable`	Enable cloud runners for the org.
POST	`/organizations/{orgId}/cloud-runners/disable`	Disable cloud runners.

Get config

curl https://api.flightstack.voostack.com/organizations/$ORG_ID/cloud-runners/config \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "enabled": true,
  "machineType": "c2-standard-4",
  "image": "macos-14-xcode-16",
  "maxConcurrentInstances": 8,
  "idleMinutesBeforeShutdown": 5,
  "monthlyBudgetCents": 50000,
  "burstAllowedOver": "self-hosted"
}

Update config

curl -X PUT https://api.flightstack.voostack.com/organizations/$ORG_ID/cloud-runners/config \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "machineType": "c2-standard-8",
    "maxConcurrentInstances": 16,
    "monthlyBudgetCents": 100000
  }'

Instances

Method	Path	Purpose
GET	`/organizations/{orgId}/cloud-runners/instances`	List active cloud-runner instances.
POST	`/organizations/{orgId}/cloud-runners/instances/{instanceId}/terminate`	Force-terminate an instance.

A cloud-runner instance is reported as soon as it boots and starts heartbeating. The agent running inside the instance posts back to /buildagent/{id}/cloud-runner/{instanceId}/ready when it’s accepting jobs.

Usage

Method	Path	Purpose
GET	`/organizations/{orgId}/cloud-runners/usage`	Usage for a date range. Query: `startDate=`, `endDate=`.
GET	`/organizations/{orgId}/cloud-runners/usage/current`	Usage for the current billing month.

curl "https://api.flightstack.voostack.com/organizations/$ORG_ID/cloud-runners/usage/current" \
  -H "Authorization: Bearer $TOKEN"

Response includes minutes used per machine type, cumulative cost (cents), and a per-day breakdown.