---
title: "Cluster-availability probe"
method: GET
path: "/clusterz"
tags: ["Health"]
---

# Cluster-availability probe

`GET /clusterz`

## Request

- Base URL: `http://localhost:9000`
- URL: `http://localhost:9000/clusterz`
- Auth: one of:
  - HTTP bearer
  - none

Returns 200 only when the node is part of a healthy cluster (Raft state
healthy and a leader elected). Disk and clock skew gate writes (see
admission), not cluster readiness. Returns 503 otherwise. Use this
for external monitoring or any client that needs to wait until the node
can actually serve cluster-dependent traffic. Kubernetes readiness
probes should target `/readyz` instead — this endpoint MUST NOT gate
StatefulSet ordering, otherwise the cluster cannot recover from a
full-kill cold start.

## Response `200`

Node is part of a healthy cluster

- HealthResponse
  - `data` object, required
    - `status` string, required: Health status (e.g. "ok")

## Other responses

- `503`: Service unavailable — the server cannot serve the request right now but an immediate retry can succeed. The `errorCode` field discriminates the cause: `NO_LEADER` (no elected Raft leader), `CACHE_HORIZON_EXCEEDED` (admission snapshot too old, retry against a fresh one), `UNAVAILABLE` (an internal forwarded stream was torn down mid-transfer), or the reason of any domain error of the unavailable kind (e.g. `INDEX_BUILDING`).

## Changes

- **2026-11-03** `f5e817eca038`: 1 info
  - api operation id `clusterz` removed and replaced with `v3Clusterz`
- **2026-09-30** `b747efd5cd77`: 1 info
  - endpoint added
- **2026-09-29** `6ff73ac9a6bd`: 1 breaking
  - api path removed without deprecation
- **2026-09-01** `4d28c76b4328`: 1 info
  - endpoint added
- **2026-08-28** `fe945da1b75d`: 1 breaking
  - api path removed without deprecation

[Operation history](https://skmtc.dev/formancehq/apis/ledger-api/changes/clusterz/get.md)

---

[API](https://skmtc.dev/formancehq/apis/ledger-api.md) - [All operations](https://skmtc.dev/formancehq/apis/ledger-api/llms.txt) - [OpenAPI document](https://skmtc.dev/formancehq/apis/ledger-api/revisions/f5e817eca038?raw)