Current host resources for core and every poller reporting telemetry.

GET

/api/v1/system/hosts

curl --request GET \
  --url https://example.com/api/v1/system/hosts \
  --header 'Authorization: Bearer <token>'

Reads st.admin opportunistically rather than taking the Admin extractor: core is answering the request, so it can always report itself. Skeleton mode returns just core rather than 503.

Authorizations

• bearer

Responses

200

Core plus every poller reporting host telemetry

Media typeapplication/json

Core plus every poller that reports host telemetry.

object

hosts

required

Array<object>

One self-monitored host: current resource values for the core process’s host (role="core") or a poller’s (role="poller").

object

cpu_pct

Current CPU utilization % (0–100); null when no sample yet.

number | null format: double

disk_used_pct

Highest watched-filesystem used %, for at-a-glance columns; null when none has a capacity.

number | null format: double

disks

required

Current per-watched-filesystem usage.

Array<object>

Usage of one watched filesystem (or a store-size proxy, e.g. the PostgreSQL database size which core cannot statvfs). size_bytes == 0 means “total capacity unknown” — the value is a bare growing size (used only), not a fraction of a disk.

object

mount

required

Friendly mount label (e.g. root, metrics, database) — a stable, low-cardinality name, never a raw device path, so it is safe as a TSDB label.

string

size_bytes

required

Total filesystem capacity in bytes; 0 when unknown (capacity not measurable).

integer format: int64

used_bytes

required

Bytes in use on the filesystem (or the store’s size when size_bytes == 0).

integer format: int64

instance

required

core or the poller id.

string

load1

Current 1-minute load average; null when no sample / unavailable on the platform.

number | null format: double

mem_total_bytes

Total physical memory, bytes; null when no sample.

integer | null format: int64

mem_used_bytes

Memory in use, bytes; null when no sample.

integer | null format: int64

mem_used_pct

Memory-used %, derived; null when total is unknown.

number | null format: double

online

required

Whether the source is currently reporting (core is always online; a poller within its heartbeat window).

boolean

pool

Pool the poller serves; null for core.

string | null

role

required

"core" or "poller".

string

Example^generated

{
  "hosts": [
    {
      "cpu_pct": 1,
      "disk_used_pct": 1,
      "disks": [
        {
          "mount": "example",
          "size_bytes": 1,
          "used_bytes": 1
        }
      ],
      "instance": "example",
      "load1": 1,
      "mem_total_bytes": 1,
      "mem_used_bytes": 1,
      "mem_used_pct": 1,
      "online": true,
      "pool": "example",
      "role": "example"
    }
  ]
}

401

No valid bearer token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Role lacks the view permission

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}