backups

Backups of the guests of a Proxmox VE cluster, by its API

Returns, for each virtual machine and container of a Proxmox VE cluster, or of a single Proxmox VE server, the number of backups kept and the age of the newest, read in the storage that holds backups (a directory, NFS, CIFS, a Proxmox Backup Server) through the Proxmox VE API, behind an API token. A backup that failed leaves no archive: the age of the newest grows, and says it. Three watches are offered, each one set on the probe.

Versions

Proxmox VE from 6.2, the first to give API tokens; the routes read have kept their form since. Generic: no folder of version.

How it works

The token goes in the header Authorization: PVEAPIToken=<token> of each request.

1. GET https://<host:address>:8006/api2/json/cluster/resources?type=storage: each storage as each node sees it. Those whose content includes backup are read; a shared one ("shared": 1) once, from the first node that reads it, a local one on its node.
2. GET https://<host:address>:8006/api2/json/nodes/<node>/storage/<storage>/content?content=backup for each of them:

{"data": [{"volid": "nfs-backup:backup/vzdump-qemu-101-2026_10_26-01_00_03.vma.zst", "vmid": 101, "ctime": 1793062803, "size": 2147483648, "format": "vma.zst"}]}

3. GET https://<host:address>:8006/api2/json/cluster/resources?type=vm: the guests that exist now.

• A guest is named by its id (VMID: 101), as in proxmox/https/guests.
• The backups kept are the archives of the guest in every backup storage read; the age of the newest is the time since its ctime, in hours. A guest with no backup returns 0 and no age.
• A backup storage that no node could read (not available, or answering another code than 200: a backup server down) counts in "Backup storage unread": the backups it holds are then missing from the count and the ages, which may raise "Newest backup too old" for that reason.
• A code 401 (the token refused) stops the collector misconfigured, a code 403 on the lists too; any other code but 200 on the lists stops it unreachable.

The token comes from protocol:http:token, a secret variable: it only goes in the header. The answers are not secret.

Prerequisites

• The address of any node of the cluster as the host's address, reachable from the poller in HTTPS on port 8006, or the port set in the variable proxmox:port when a proxy serves the API on another. The certificate of the node is issued by the cluster's own authority: trust it by that authority (/etc/pve/pve-root-ca.pem) under protocol:tls:authorities, by its pinned fingerprint in protocol:http:fingerprint, or by the first fingerprint trusted in the tab "Security".
• An API token in protocol:http:token, written <user>@<realm>!<token id>=<secret>, of a user given the role PVEAuditor, read-only, on /: see the collector proxmox/https/nodes for the three pveum commands. Listing the content of a storage asks Datastore.Audit on it, which PVEAuditor gives.

Variables

Outputs

Watches

Limits

• Every guest is judged, those never meant to be backed up and the templates included: leave them out by the selection of the probe (Guests: All except 9000, 90*). A guest backed up weekly needs its own probe, with its own thresholds.
• The failure of a backup job is not read here: its trace is the age that grows. The result of the last backup job of each node is the collector proxmox/https/backup-tasks.
• One listing per backup storage at each run: on a Proxmox Backup Server that keeps many backups, the listing is long.
• The address is written into the URL as is: an IPv6 address must be given as a name.
• Not checked against a Proxmox VE: the routes and fields are those of the API viewer of Proxmox VE (pve-docs/api-viewer) and of its source (PVE/API2Tools.pm, which writes shared and content for each storage).