# Health & System Endpoints (/operate/observability/api-reference/health-system)



These operational endpoints cover health checks, readiness, billing, and Prometheus
metrics on the management API port (`:8080`). They are **not** gated by the readiness guard
described on the [Management API overview](/operate/observability/api-reference), so they are
available as soon as the HTTP server starts.

## GET /health [#get-health]

Returns the process health as plain text. This is the **liveness** signal.

**Response:** `text/plain`

| Condition   | HTTP status | Body          |
| ----------- | ----------- | ------------- |
| Healthy     | 200         | `healthy`     |
| Not healthy | 500         | `not healthy` |

```text
GET /health
→ 200 OK
healthy
```

Use this for a liveness probe or a health-indicator badge; poll every 5–10 seconds.

## GET /ready [#get-ready]

Returns the readiness state as a raw JSON `HealthState` object (no envelope). This is the
**Kubernetes readiness probe** endpoint.

**Response:** `application/json`

| Condition | HTTP status | Body               |
| --------- | ----------- | ------------------ |
| Ready     | 200         | `HealthState` JSON |
| Not ready | 500         | `HealthState` JSON |

```json
{
  "is_healthy": true,
  "is_ready": true,
  "current_leadership_role": "leader"
}
```

| Field                     | Type      | Description                                                                       |
| ------------------------- | --------- | --------------------------------------------------------------------------------- |
| `is_healthy`              | `boolean` | Whether the process is healthy                                                    |
| `is_ready`                | `boolean` | Whether the node is ready to accept traffic                                       |
| `current_leadership_role` | `string`  | The cluster leadership role: `leader`, `follower`, or empty for a standalone node |

Use this for a readiness probe and to display each node's cluster leadership role.

## Kubernetes probes [#kubernetes-probes]

Wire `/health` and `/ready` to the container's liveness and readiness probes on the
management API port (`8080`):

```yaml
livenessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 5
```

For full deployment settings, see [Kubernetes configuration](/configure/kubernetes).

## GET /billing [#get-billing]

Returns a usage summary for the current node, wrapped in the standard response envelope.

**Response:** standard envelope with `Billing` data.

| Field          | Type      | Description                        |
| -------------- | --------- | ---------------------------------- |
| `hostname`     | `string`  | Node hostname                      |
| `uptime`       | `float64` | Uptime in seconds                  |
| `messages`     | `int64`   | Total messages processed           |
| `volume`       | `float64` | Total data volume in bytes         |
| `last_message` | `int64`   | Unix timestamp of the last message |

```json
{
  "error": false,
  "error_string": "",
  "data": {
    "hostname": "kubemq-node-0",
    "uptime": 3600,
    "messages": 50000,
    "volume": 1024000,
    "last_message": 1709312400
  }
}
```

## GET /metrics [#get-metrics]

Returns all registered metrics in Prometheus text exposition format. This is the endpoint
Prometheus scrapes; it is not meant for direct UI consumption — use the snapshot endpoints
for dashboard data instead.

**Response:** `text/plain` (Prometheus exposition format)

For the full metric catalog, labels, and PromQL examples, see
[Prometheus Metrics](/operate/observability/metrics).

## GET /kill [#get-kill]

Disabled. Always returns HTTP 404 in plain text and does **not** use the standard envelope.
Reserved — do not use.

```text
GET /kill
→ 404 Not Found
{"message":"not found"}
```