List Nodes
List every node in the cluster, with live health.
| Endpoint | Method | Admin Required |
|---|---|---|
/api/v1/admin/cluster/nodes | GET | Yes |
Returns every node registered in the cluster, sorted by join time, with a live health flag. Only meaningful when cluster mode is enabled - on a node not part of a cluster, this returns an empty array.
Response
[
{
"id": "B1C2D3E4-F5G6-7890-HIJK-LM1234567890",
"address": "http://alarik-1:8080",
"status": "active",
"joinedAt": "2025-01-15T10:30:00Z",
"lastHeartbeatAt": "2025-01-15T12:04:10Z",
"isHealthy": true,
"totalBytes": 500107862016,
"availableBytes": 210453647360,
"isNearFull": false
},
{
"id": "C2D3E4F5-G6H7-8901-IJKL-MN2345678901",
"address": "http://alarik-2:8080",
"status": "draining",
"joinedAt": "2025-01-15T10:31:02Z",
"lastHeartbeatAt": "2025-01-15T12:04:05Z",
"isHealthy": true,
"totalBytes": 500107862016,
"availableBytes": 41943040,
"isNearFull": true
}
]
Response Fields
id
string
The node's identity - a UUID persisted across restarts (
Storage/cluster_node_id), never regenerated as long as the node's storage volume is intact.address
string
The node's internally-reachable base URL (
CLUSTER_NODE_ADDRESS), used by peers to forward requests and replicate objects to it.status
string
active, draining, or removed. Only active nodes are eligible for new object placement.joinedAt
string
ISO 8601 timestamp of when this node first registered.
lastHeartbeatAt
string
ISO 8601 timestamp of the node's most recent heartbeat.
isHealthy
boolean
true when status is activeand the heartbeat hasn't gone stale (60 seconds). A node can show status: "active" with isHealthy: false briefly if it's unreachable but hasn't been explicitly drained.totalBytes
number | null
This node's total disk capacity in bytes, self-reported on its heartbeat.
null until the node's first heartbeat since upgrading to a version that reports capacity.availableBytes
number | null
This node's free disk space in bytes, self-reported on its heartbeat.
null under the same conditions as totalBytes.isNearFull
boolean
true when free space is below CLUSTER_MIN_FREE_PERCENT (default 10%). See Capacity-aware placement - a near-full node hands off new-write coordination to a less-full peer, but keeps serving reads and never has its existing data evicted automatically.