v0.1.7

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


  1. curl http://192.168.0.11:8080/api/health
  2. # ok

Confirms only that the process is alive; it does not check Proxmox or the state files.

GET /api/vm/:id/status


  1. curl http://192.168.0.11:8080/api/vm/120/status
  2. # running

CaseResponse
SuccessText: the value after the colon in qm status (running / stopped); unknown when the output cannot be parsed
Non-numeric :id400 JSON {"error": "invalid VM ID"}
qm status fails500 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


  1. curl "http://192.168.0.11:8080/api/vm/list?disable=0"

disableReturns
omittedEvery VM, disabled entries included
0Running and not disabled
1Stopped and not disabled

  1. {
  2. "count": 1,
  3. "list": [
  4. { "vmid": 120, "name": "web-120", "os": "debian", "running": true, "node": "pve1",
  5. "cpu": 2, "disk": 32, "memory": 4, "memory_used": 1 }
  6. ],
  7. "cluster": [
  8. { "node": "pve1", "max_cpu": 16, "max_memory": 62.7, "cpu": 12.5, "memory": 6.38,
  9. "memory_used": 1.59, "disk": 93.93, "running": true }
  10. ],
  11. "data": [
  12. { "vmid": 120, "name": "web-120", "os": "debian", "running": true, "node": "pve1",
  13. "cpu": 2, "disk": 32, "memory": 4, "memory_used": 1 }
  14. ]
  15. }

list[]


FieldDescription
vmid / name / nodeFrom pvesh get /cluster/resources --type vm
osThe VM's Proxmox tag (this service writes debian / ubuntu / rockylinux); - for disabled entries
runningstatus == "running"; always true for disabled entries
cpuvCPU count
disk / memory / memory_usedGiB, integer-truncated

Sorted by ascending vmid.

cluster[]


FieldDescription
node / runningNode name and whether it is online
max_cpuNode logical CPU count
max_memory / diskGiB, rounded to two decimals
cpuSum of listed VMs' vCPUs ÷ max_cpu (%)
memorySum of listed VMs' allocated memory ÷ max_memory (%)
memory_usedSum 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.
中文