Every node the cluster reports, with capacity, uptime, and PVE version.

Read-only and idempotent. A single-node installation is not a degenerate case: it reports one node and no cluster-wide quorum. An offline or unreadable node yields a partial result with a warning naming it, never an exception that hides the nodes that answered.

CPU, memory, swap, and per-mount filesystem utilization for exactly one node.

Read-only and idempotent. The per-mount figures and the memory detail come from the node itself, so a node that cannot be reached yields a partial result naming it rather than an exception. allocation compares what the resident guests are configured to claim against what the node has.

Every LXC and VM in the cluster, or a filtered subset.

Read-only and idempotent. Stopped guests are included: they are the ones a caller is most likely to have forgotten about. A filter that matches nothing returns an empty list, not an error. A guest the cluster reports as unknown -- which is what it says about a guest on a node it cannot reach -- is still listed, with the result marked partial.

One guest's configuration, on exactly the node named.

Read-only and idempotent. Returns cores, memory, swap, disks and their storage, network interfaces with bridge, address, and gateway, the unprivileged flag, the OS template, boot-on-start, and features. It never returns a password, a cloud-init password, or an SSH public key: there is no field for one.

A vmid the cluster does not report on the node named raises a structured error naming both. A config that cannot be read yields a partial result with a warning.

One guest's live status, on exactly the node named.

Read-only and idempotent. Returns state, uptime, CPU, memory, swap, disk read and write, network in and out, and the high-availability state.

A stopped guest is an answer, not a failure: it returns this model with its state, a warning saying the live figures are not meaningful, and partial set. A vmid the cluster does not report on the node named raises a structured error naming both.

Storage entries with their per-node status and a cluster-wide aggregate.

Read-only and idempotent. With node given, only that node's storage is reported and its own pvesm status is what is read; without it, the first node in the profile that answers supplies the free-space figures and every other node reports available_bytes as None.

A storage that cannot be read yields a warning and partial, never an exception that hides the rest of the cluster.

Snapshots for exactly one guest, with parent, description, timestamp, and RAM state.

Read-only and idempotent. A guest that has never been snapshotted returns an empty list: the endpoint always reports a current pseudo-entry, which is not a snapshot and is not counted as one. Absence is an answer, not an error.

The node and vmid are bound together before anything is read, so this never answers about a guest on a node the caller did not name.

Backup volumes with their guest, format, size, and timestamp, plus recency per guest.

Read-only and idempotent. Recency covers every guest in scope whether or not it has a backup, because a guest missing from a backup listing is the most important thing such a listing reports.

A storage that cannot be listed yields a warning and partial; the storages that could be read are still reported.

Whether one address inside the profile's configured networks is in use.

Read-only and idempotent. Combines every guest configuration in the cluster, the neighbour table of one node, and one probe, and reports the evidence for its conclusion.

Refuses any address outside permitted_networks, before any command is issued. Raises ProfileError naming the setting when no network is configured; it never guesses a range.

Reports inconclusive rather than guessing. A partial answer may report in_use but never free: absence of evidence is not evidence of absence, and a wrong free means a duplicate address on a live network.

Docker containers inside one LXC guest, on exactly the node named.

Read-only and idempotent. Reports each container's name, image, state, health verdict, creation time, published ports, compose project and service, and attached networks.

Environment variables are never returned, and neither are container labels or command lines: there is no field for any of them.

None of the four absences is an error. Docker not installed and a QEMU guest are both complete answers with partial false and no warning, and they are told apart by docker_available: false means the guest was asked and has no Docker, null means the question does not apply because there is no pct exec path into a QEMU VM. A guest that is not running and a listing that could not be read are questions that could not be asked: docker_available false, partial true, and a warning saying which.

One compose project inside one LXC guest, on exactly the node named.

Read-only and idempotent. Reports the project's status, working directory, configuration file paths, and for each service its image, state, health verdict, working directory, published ports, attached networks, and persistent mounts, plus the networks the project owns.

Mount paths are returned; mount contents are never read -- no command form this server can issue opens a file. Environment variables are never returned, and neither are container labels or command lines.

An empty services list is an answer. A guest without Docker, a QEMU guest, and a guest that simply does not run a project under that name all return one with partial false and no warning: each is a question that was asked and definitively answered. A guest that is not running and a listing that could not be read return one with partial true and a warning, because those are questions that could not be asked. A single container whose inspection fails still appears as a service, carrying what the container listing knew.

One consolidated read of a guest, on exactly the node named.

Read-only and idempotent. Combines live status, resource pressure against the guest's configured limits, filesystem headroom, Docker container health counts, snapshot and backup recency, and a short list of concrete concerns. Prefer this over calling get_guest_status, list_snapshots, list_backups, and list_guest_containers separately when the question is "how is this guest doing".

Each entry in concerns is a whole sentence naming both the observation and the threshold it crossed, so it can be quoted to an operator without further interpretation. An empty list means nothing that was read crossed a threshold; it does not mean everything was read, which partial and warnings report.

Three states stay distinguishable and none of them is an error. A guest that is not running reports its state, a warning, and no resource figures, because the zeroes the cluster carries for it describe nothing. A guest without Docker reports docker_available false and no container counts. A guest with no backup reports backup_count 0 and a null age, never an age of zero.

A vmid the cluster does not report on the node named raises a structured error naming both. Anything that could not be read yields a warning and partial, never an exception that hides the rest of the answer.