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

# Health API

> Liveness, readiness, and summary metrics for a Nasiko server.

Three unauthenticated routes report whether a Nasiko server is up and ready. Point load balancers and orchestrator probes at them. The CLI uses them too: `nasiko connect <url>` and `nasiko doctor` call `/health`, and `nasiko status` calls `/readiness` and `/metrics`. See [Setup commands](https://docs.nasiko.com/reference/cli/setup.md).

They sit at the server root, not under `/api`, and need no token. They aren't in the generated OpenAPI spec.

| Route | Use it for | Healthy answer |
| - | - | - |
| `GET /health` | Liveness: is the process serving HTTP? | `200` |
| `GET /readiness` | Readiness: can it reach its database and container runtime? | `200` |
| `GET /metrics` | A count of agents, builds, users, and sessions | `200` |

## Liveness

`GET /health`

Returns `200` with the plain-text body `ok` whenever the server process is serving requests. It checks no dependencies, so a failing database doesn't fail it. Use it as a liveness probe, where a failure should restart the server.

```bash theme={null}
curl https://nasiko.example.com/health
```

```
ok
```

## Readiness

`GET /readiness`

Checks the server's dependencies and reports each one. Use it as a readiness probe, where a failure should stop traffic to this instance without restarting it.

```bash theme={null}
curl -i https://nasiko.example.com/readiness
```

**Response** `200 OK` when ready:

```json theme={null}
{ "status": "ready", "postgres": true, "redis": true, "orchestrator": true }
```

**Response** `503 Service Unavailable` when not:

```json theme={null}
{ "status": "degraded", "postgres": true, "redis": true, "orchestrator": false }
```

| Field | Check |
| - | - |
| `postgres` | The server can run a query against Postgres |
| `redis` | The server can reach Redis and get a reply to `PING` |
| `orchestrator` | The server can list containers from its container runtime: Docker or Kubernetes |
| `status` | `ready` or `degraded` |

The status code depends on `postgres` and `orchestrator` only. A Redis failure shows `"redis": false` but still returns `200` and `"status": "ready"`. `nasiko status` is stricter: it reports the cluster as unhealthy, and exits with code `1`, when any of the three checks fails.

## Metrics

`GET /metrics`

A JSON summary of the server's contents. `nasiko status` prints part of it. This is a JSON object, not Prometheus text format. The server exports its OpenTelemetry metrics separately, to the endpoint set by `OTEL_EXPORTER_OTLP_ENDPOINT`. See [Configuration](https://docs.nasiko.com/self-hosting/configuration.md).

```bash theme={null}
curl https://nasiko.example.com/metrics
```

**Response** `200 OK`

```json theme={null}
{
  "agents_total": 12,
  "agents_running": 9,
  "containers_total": 10,
  "users_total": 34,
  "builds_total": 187,
  "builds_pending": 1,
  "chat_sessions_total": 2210,
  "token_usage_total": 15873
}
```

| Field | Description |
| - | - |
| `agents_total` | Agents that haven't been deleted |
| `agents_running` | Agents whose status is `running` |
| `containers_total` | Containers the container runtime reports |
| `users_total` | User accounts |
| `builds_total` | Builds ever created |
| `builds_pending` | Builds that are `queued` or `building` |
| `chat_sessions_total` | Chat sessions, including reported coding-agent sessions |
| `token_usage_total` | Traces with recorded model usage. Despite the name, this counts traces, not tokens. For token and cost totals, use [TokenOps](https://docs.nasiko.com/tokenops/attribution.md) |

A count that can't be read is reported as `0` rather than failing the request. Pair `/metrics` with `/readiness` to tell an empty server from an unhealthy one.

> [!NOTE]
>
> `/metrics` needs no sign-in, so anyone who can reach the server can read these counts. To keep them private, don't expose `/metrics` outside your network at the load balancer or ingress.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.