Query Endpoints
Last updated
This page covers the three read-only endpoints: health check, single VM status, and the cluster VM list. Query endpoints do not check
ALLOW_IPS.GET /api/health
- curl http://192.168.0.11:8080/api/health
- # ok
Confirms only that the process is alive; it does not check Proxmox or the state files.
GET /api/vm/:id/status
- curl http://192.168.0.11:8080/api/vm/120/status
- # running
| Case | Response |
|---|---|
| Success | Text: the value after the colon in qm status (running / stopped); unknown when the output cannot be parsed |
Non-numeric :id | 400 JSON {"error": "invalid VM ID"} |
qm status fails | 500 failed to get VM status: ... |
Runs locally on the main node only; querying a VM on another node fails, so use
/vm/list instead.GET /api/vm/list
- curl "http://192.168.0.11:8080/api/vm/list?disable=0"
disable | Returns |
|---|---|
| omitted | Every VM, disabled entries included |
0 | Running and not disabled |
1 | Stopped and not disabled |
- {
- "count": 1,
- "list": [
- { "vmid": 120, "name": "web-120", "os": "debian", "running": true, "node": "pve1",
- "cpu": 2, "disk": 32, "memory": 4, "memory_used": 1 }
- ],
- "cluster": [
- { "node": "pve1", "max_cpu": 16, "max_memory": 62.7, "cpu": 12.5, "memory": 6.38,
- "memory_used": 1.59, "disk": 93.93, "running": true }
- ],
- "data": [
- { "vmid": 120, "name": "web-120", "os": "debian", "running": true, "node": "pve1",
- "cpu": 2, "disk": 32, "memory": 4, "memory_used": 1 }
- ]
- }
list[]
| Field | Description |
|---|---|
vmid / name / node | From pvesh get /cluster/resources --type vm |
os | The VM's Proxmox tag (this service writes debian / ubuntu / rockylinux); - for disabled entries |
running | status == "running"; always true for disabled entries |
cpu | vCPU count |
disk / memory / memory_used | GiB, integer-truncated |
Sorted by ascending
vmid.cluster[]
| Field | Description |
|---|---|
node / running | Node name and whether it is online |
max_cpu | Node logical CPU count |
max_memory / disk | GiB, rounded to two decimals |
cpu | Sum of listed VMs' vCPUs ÷ max_cpu (%) |
memory | Sum of listed VMs' allocated memory ÷ max_memory (%) |
memory_used | Sum of listed VMs' used memory ÷ max_memory (%) |
Percentages count only VMs that pass the
disable filter. Sorted by node name.data
Deprecated; mirrors
list for older clients.