Fleet endpoints

Three read-only endpoints for fleet visibility. All require X-Platform-Key.

GET /engines

List all engines for the calling product, optionally filtered by status. Paginated.

Request

GET /engines?status=running&limit=100&offset=0
X-Platform-Key: pk-sept-...

Query	Type	Default	Purpose
`status`	string	(any)	Filter to one of `provisioning`, `running`, `sleeping`, `stopped`, `failed`, `destroying`.
`limit`	int	100	Max results per page.
`offset`	int	0	Pagination offset.

Response (200)

{
  "engines": [
    {
      "engine_id": "...",
      "user_id": "...",
      "status": "running",
      "url": "http://...",
      "engine_version": "september-engine:2.3.0",
      "created_at": "...",
      "last_health_at": "..."
    }
  ],
  "total": 247
}

Note: api_key is not included in the list response. To get a key, use /admit or GET /engines/{user_id} for one specific user.

GET /status

Fleet health snapshot. One JSON object that summarizes the entire product’s fleet state.

Request

GET /status
X-Platform-Key: pk-sept-...

Response (200)

{
  "total": 247,
  "by_status": {
    "running": 240,
    "sleeping": 4,
    "stopped": 1,
    "failed": 2
  },
  "health": "ok",
  "unhealthy_count": 2
}

Field	Purpose
`total`	All engines in any non-destroyed state.
`by_status`	Count per state.
`health`	Overall: `ok` (zero failed), `degraded` (some failed), `critical` (high % failed).
`unhealthy_count`	Engines in `failed` state.

Useful for ops dashboards and “is the product healthy?” checks.

GET /metrics

Rolling-hour operational metrics.

Request

GET /metrics
X-Platform-Key: pk-sept-...

Response (200)

{
  "provisions_1h": 42,
  "crashes_1h": 1,
  "restarts_1h": 5,
  "avg_boot_ms": 4350,
  "total_provisions": 18047,
  "total_destroys": 17800
}

Field	Purpose
`provisions_1h`	New engines created in the last hour.
`crashes_1h`	Engines that transitioned to `failed` in the last hour.
`restarts_1h`	Auto-restarts attempted in the last hour.
`avg_boot_ms`	Average boot duration over recent provisions.
`total_provisions`	Lifetime count.
`total_destroys`	Lifetime count.

Numbers come from the audit log — see Audit for the schema.

What’s not here

Per-user metrics. Use the audit log directly: SELECT ... FROM audit_log WHERE user_id = ....
Per-engine metrics. Same.
Cost. The orchestrator doesn’t track LLM cost; that’s at the engine layer (or upstream).
Latency distributions. No histograms. If you need them, scrape external metrics from the engine /health and aggregate yourself.

Architecture

BAP Engine

Engineering

Fleet endpoints

GET /engines

Request

Response (200)

GET /status

Request

Response (200)

GET /metrics

Request

Response (200)

What’s not here

See also

​GET /engines

​Request

​Response (200)

​GET /status

​Request

​Response (200)

​GET /metrics

​Request

​Response (200)

​What’s not here

​See also

GET /engines

Request

Response (200)

GET /status

Request

Response (200)

GET /metrics

Request

Response (200)

What’s not here

See also