--- title: Look after your node: health, version, status, utilisation and its disks slug: look-after-your-node date: 2026-10-12 author: Semurg section: how-to tags: [operations, monitoring, install, how-to] summary: The few calls that tell you how a node is doing: whether it is up, which release it runs, what it holds, how hard its disks and cores are working, and whether its landing area and storage are in order. status: published covers: [route:GET /api/health, route:GET /api/version, route:GET /v1/status, route:GET /v1/licence, route:GET /v1/cluster/util, route:GET /v1/cluster/conveyor, route:GET /v1/cluster/customs, route:GET /v1/cluster/nodes, route:GET /v1/cluster/nodes/{fp}] --- A node you run should be able to tell you how it is doing without anyone logging in to it. These calls do that. Each answers JSON; with your API token you get the operator detail, and without it a caller from elsewhere gets only a coarse summary, so a networked node never hands its internals to a stranger. > Diagram node-calls: Health and version answer anyone; with the token, status says what the node is and holds, licence its licence state, util how hard it works, conveyor what memory serves, customs whether its disks are in order, and nodes which nodes it knows. ## Is it up, and which release is it? ```bash runnable kind=shell-node needs=none curl -sS http://localhost:4000/api/health ``` ```expect expect: the node's health as JSON assert: json:type=="object" ``` ```bash runnable kind=shell-node needs=none curl -sS http://localhost:4000/api/version ``` ```expect expect: the release the node runs, with its commit assert: json:type=="object" ``` The version is the one to quote when you report a problem, and the one the update command compares with the latest published release. ## What is it, and what does it hold? `/v1/status` describes the node: its identity, its licence state, what it can do and what its store holds. ```bash runnable kind=shell-node needs=token export SEMURG_API_TOKEN= curl -sS http://localhost:4000/v1/status -H "Authorization: Bearer $SEMURG_API_TOKEN" ``` ```expect expect: the node's identity, capabilities and store counts assert: json:type=="object" ``` `/v1/licence` reports the licence state. A single node runs the full engine with no licence key: on a node of its own nothing needs licensing, and a key matters only when a node joins a cluster. ```bash runnable kind=shell-node needs=token export SEMURG_API_TOKEN= curl -sS http://localhost:4000/v1/licence -H "Authorization: Bearer $SEMURG_API_TOKEN" ``` ```expect expect: the licence state assert: json:.ok==true and (.licence|type)=="object" ``` ## How hard is it working? `/v1/cluster/util` is a live snapshot of the machine while it works: each disk's throughput, each core's load and the memory bandwidth in use, per node and in total. It is the same measurement Semurg publishes beside its own benchmark figures, so you can read your node the way we read ours. One caveat: the memory-bandwidth figure in it is being re-proven after our 2026-10-11 control audit, which found that it reads only part of the engine's own traffic, so for now treat it as a lower bound. ```bash runnable kind=shell-node needs=token export SEMURG_API_TOKEN= curl -sS http://localhost:4000/v1/cluster/util -H "Authorization: Bearer $SEMURG_API_TOKEN" ``` ```expect expect: a utilisation snapshot for the node assert: json:.ok==true and (.util|type)=="object" ``` `/v1/cluster/conveyor` shows the counters of the machinery that decides what is in memory: how much the memory tier is serving, how far ahead the prefetch is reading, and how much the janitor has packed together. Read it before and after a workload, and the difference says whether that workload was served from memory or went to disk. ```bash runnable kind=shell-node needs=token export SEMURG_API_TOKEN= curl -sS http://localhost:4000/v1/cluster/conveyor -H "Authorization: Bearer $SEMURG_API_TOKEN" ``` ```expect expect: the memory tier, prefetch and janitor counters assert: json:.ok==true and (.conveyor|type)=="object" ``` ## Are its disks in order? Each data disk is split into a landing area, where data arriving in a foreign format waits to be converted, and the store itself. `/v1/cluster/customs` checks that split on every disk and answers with one verdict, `green`, `red` or `could_not_judge`, and, for the operator, each disk's state. > Diagram disk-split: Each data disk holds a landing area, where data in a foreign format waits to be converted, and the store itself; the customs check reads that split on every disk and answers green, red or could not judge. ```bash runnable kind=shell-node needs=token export SEMURG_API_TOKEN= curl -sS http://localhost:4000/v1/cluster/customs -H "Authorization: Bearer $SEMURG_API_TOKEN" ``` ```expect expect: the landing area and store check, with its verdict assert: json:.ok==true and (.customs.verdict|type)=="string" ``` ## Which nodes are there? `/v1/cluster/nodes` lists the nodes the cluster knows; on a node of its own, that is itself. `/v1/cluster/nodes/` gives one node's status in detail. ```bash runnable kind=shell-node needs=token export SEMURG_API_TOKEN= curl -sS http://localhost:4000/v1/cluster/nodes -H "Authorization: Bearer $SEMURG_API_TOKEN" ``` ```expect expect: the list of nodes this node knows assert: json:type=="object" ``` ## Next - Keep the node current with [the update guide](/blog/update-your-node-to-the-latest-release). - Adding a second node is not covered here yet; it will be, once it works from a published release.