> ## Documentation Index
> Fetch the complete documentation index at: https://internal.september.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# Fleet endpoints

> List engines, fleet status, and rolling metrics.

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

```http theme={null}
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)

```json theme={null}
{
  "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

```http theme={null}
GET /status
X-Platform-Key: pk-sept-...
```

### Response (200)

```json theme={null}
{
  "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

```http theme={null}
GET /metrics
X-Platform-Key: pk-sept-...
```

### Response (200)

```json theme={null}
{
  "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](../../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.

## See also

* [Audit](../../audit) — the underlying log behind these metrics.
* [Health](../../health) — what `crashes_1h` and `restarts_1h`
  count.