VM Data API¶

These three models store per-virtual-machine data synced from Proxmox: backup records, snapshot records, and task history entries.

For common API conventions (authentication, pagination, nested serializers), see API Overview.

VM Backup¶

A backup record for a virtual machine or container, as reported by Proxmox storage.

GET    /api/plugins/proxbox/backups/
GET    /api/plugins/proxbox/backups/{id}/
POST   /api/plugins/proxbox/backups/
PUT    /api/plugins/proxbox/backups/{id}/
PATCH  /api/plugins/proxbox/backups/{id}/
DELETE /api/plugins/proxbox/backups/{id}/

Example — list all backups for a virtual machine:

curl -H "Authorization: Token <token>" \
     "http://netbox.example.com/api/plugins/proxbox/backups/?virtual_machine_id=10"

Example — filter for PBS VM backups:

curl -H "Authorization: Token <token>" \
     "http://netbox.example.com/api/plugins/proxbox/backups/?format=pbs-vm"

Filterable fields: id, proxmox_storage, virtual_machine, subtype, format, creation_time, size, used, encrypted, volume_id, vmid

Searchable fields (?q=): virtual machine name, storage name, volume_id

Sample response:

{
  "id": 1,
  "url": "/api/plugins/proxbox/backups/1/",
  "display": "vm-100 backup (2026-04-01)",
  "proxmox_storage": {
    "id": 2,
    "url": "/api/plugins/proxbox/storage/2/",
    "display": "backup-storage",
    "cluster": {"id": 5, "name": "prod-cluster"},
    "name": "backup-storage"
  },
  "virtual_machine": {
    "id": 10,
    "url": "/api/virtualization/virtual-machines/10/",
    "display": "web-server-01",
    "name": "web-server-01"
  },
  "storage": "backup-storage",
  "subtype": {"value": "qemu", "label": "QEMU"},
  "format": {"value": "pbs-vm", "label": "PBS VM"},
  "creation_time": "2026-04-01T02:00:00Z",
  "size": 10737418240,
  "notes": "nightly backup",
  "volume_id": "vm/100/2026-04-01T02:00:00Z",
  "vmid": 100,
  "used": 8589934592,
  "encrypted": "a]b:c1:d2:e3",
  "verification_state": "ok",
  "verification_upid": "UPID:pve-node-01:...",
  "tags": [],
  "custom_fields": {},
  "created": "2026-04-01T02:05:00Z",
  "last_updated": "2026-04-01T02:05:00Z"
}

Data Model¶

Field	Type	Description
`proxmox_storage`	nested ProxmoxStorage (nullable)	Storage backend where this backup resides
`virtual_machine`	nested VirtualMachine	Backed-up virtual machine
`storage`	string	Raw Proxmox storage ID string
`subtype`	choice (nullable)	Guest type. Choices: `undefined`, `lxc`, `ct`, `qemu`, `vm`
`format`	choice (nullable)	Backup format. Choices: `undefined`, `pbs-vm`, `pbs-ct`, `zst`, `iso`, `tzst`, `tgz`, `qcow2`, `raw`, `tar`, `tbz`
`creation_time`	datetime	When the backup was created in Proxmox
`size`	integer	Backup size in bytes
`notes`	string	Free-text notes attached to the backup
`volume_id`	string	Proxmox volume identifier
`vmid`	integer	Proxmox VM ID
`used`	integer	Disk space actually used by this backup in bytes
`encrypted`	string	Encryption fingerprint from Proxmox (empty string = not encrypted)
`verification_state`	string	Last verification result (e.g. `ok`, `failed`)
`verification_upid`	string	UPID of the last verification task

VM Snapshot¶

A snapshot record for a virtual machine or container.

GET    /api/plugins/proxbox/snapshots/
GET    /api/plugins/proxbox/snapshots/{id}/
POST   /api/plugins/proxbox/snapshots/
PUT    /api/plugins/proxbox/snapshots/{id}/
PATCH  /api/plugins/proxbox/snapshots/{id}/
DELETE /api/plugins/proxbox/snapshots/{id}/

Example — list all snapshots for a virtual machine:

curl -H "Authorization: Token <token>" \
     "http://netbox.example.com/api/plugins/proxbox/snapshots/?virtual_machine_id=10"

Example — filter for active QEMU snapshots:

curl -H "Authorization: Token <token>" \
     "http://netbox.example.com/api/plugins/proxbox/snapshots/?subtype=qemu&status=active"

Example — search by snapshot name:

curl -H "Authorization: Token <token>" \
     "http://netbox.example.com/api/plugins/proxbox/snapshots/?q=pre-upgrade"

Filterable fields: id, proxmox_storage, virtual_machine, subtype, status, name, description, vmid, node, parent, snaptime

Searchable fields (?q=): virtual machine name, storage name, snapshot name, node, description

Sample response:

{
  "id": 1,
  "url": "/api/plugins/proxbox/snapshots/1/",
  "display": "pre-upgrade",
  "proxmox_storage": null,
  "virtual_machine": {
    "id": 10,
    "url": "/api/virtualization/virtual-machines/10/",
    "display": "web-server-01",
    "name": "web-server-01"
  },
  "name": "pre-upgrade",
  "description": "Before OS upgrade",
  "vmid": 100,
  "node": "pve-node-01",
  "snaptime": "2026-03-15T10:00:00Z",
  "parent": "current",
  "subtype": {"value": "qemu", "label": "QEMU"},
  "status": {"value": "active", "label": "Active"},
  "tags": [],
  "custom_fields": {},
  "created": "2026-03-15T10:01:00Z",
  "last_updated": "2026-04-01T00:00:00Z"
}

Data Model¶

Field	Type	Description
`proxmox_storage`	nested ProxmoxStorage (nullable)	Storage backend associated with this snapshot
`virtual_machine`	nested VirtualMachine	Snapshotted virtual machine
`name`	string	Snapshot name in Proxmox
`description`	string	Free-text snapshot description
`vmid`	integer	Proxmox VM ID
`node`	string	Node where the snapshot was created
`snaptime`	datetime	When the snapshot was taken
`parent`	string	Name of the parent snapshot (or `current`)
`subtype`	choice	Guest type. Choices: `qemu`, `lxc`
`status`	choice	Sync status. Choices: `active`, `stale` — `stale` means the snapshot no longer exists in Proxmox

VM Task History¶

A record of a Proxmox task run for a virtual machine (backup, migration, snapshot, start, stop, etc.).

GET    /api/plugins/proxbox/task-history/
GET    /api/plugins/proxbox/task-history/{id}/
POST   /api/plugins/proxbox/task-history/
PUT    /api/plugins/proxbox/task-history/{id}/
PATCH  /api/plugins/proxbox/task-history/{id}/
DELETE /api/plugins/proxbox/task-history/{id}/

Upsert on POST

POST requests are idempotent by upid. If a task history record with the same UPID already exists, the POST updates it rather than returning a conflict error.

Example — list all task history for a virtual machine:

curl -H "Authorization: Token <token>" \
     "http://netbox.example.com/api/plugins/proxbox/task-history/?virtual_machine_id=10"

Example — filter for failed backup tasks:

curl -H "Authorization: Token <token>" \
     "http://netbox.example.com/api/plugins/proxbox/task-history/?task_type=vzdump&task_state=ERROR"

Example — search by UPID:

curl -H "Authorization: Token <token>" \
     "http://netbox.example.com/api/plugins/proxbox/task-history/?q=UPID:pve-node-01"

Filterable fields: id, virtual_machine, vm_type, upid, node, pid, pstart, task_id, task_type, username, start_time, end_time, description, status, task_state, exitstatus

Searchable fields (?q=): virtual machine name, vm_type, upid, node, task_id, task_type, username, description, status, task_state, exitstatus

Sample response:

{
  "id": 1,
  "url": "/api/plugins/proxbox/task-history/1/",
  "display": "vzdump on pve-node-01 (2026-04-01)",
  "virtual_machine": {
    "id": 10,
    "url": "/api/virtualization/virtual-machines/10/",
    "display": "web-server-01",
    "name": "web-server-01"
  },
  "vm_type": "qemu",
  "upid": "UPID:pve-node-01:00001A2B:3C4D5E6F:67890ABC:vzdump:100:root@pam:",
  "node": "pve-node-01",
  "pid": 6699,
  "pstart": 1009001583,
  "task_id": "100",
  "task_type": "vzdump",
  "username": "root@pam",
  "start_time": "2026-04-01T02:00:00Z",
  "end_time": "2026-04-01T02:08:32Z",
  "description": "VM 100 backup",
  "status": "OK",
  "task_state": "stopped",
  "exitstatus": "OK",
  "tags": [],
  "custom_fields": {},
  "created": "2026-04-01T02:08:33Z",
  "last_updated": "2026-04-01T02:08:33Z"
}

Data Model¶

Field	Type	Description
`virtual_machine`	nested VirtualMachine	VM this task ran on
`vm_type`	string	Guest type (`qemu` or `lxc`)
`upid`	string	Proxmox Unique Process ID — globally unique task identifier
`node`	string	Node where the task ran
`pid`	integer	OS process ID
`pstart`	integer	Process start time (kernel ticks)
`task_id`	string	Proxmox task ID (usually the VMID)
`task_type`	string	Task type (e.g. `vzdump`, `vzmigrate`, `qmstart`, `qmstop`)
`username`	string	Proxmox user who initiated the task
`start_time`	datetime	When the task started
`end_time`	datetime (nullable)	When the task ended
`description`	string	Human-readable task description
`status`	string	Task completion status (e.g. `OK`, `error message`)
`task_state`	string	Task execution state (e.g. `stopped`, `running`)
`exitstatus`	string	Exit status string from Proxmox