get_vm_backup_snapshot_history
Read vCenter task history to measure how long a VM backup kept its snapshot open, returning cycle stats, unmatched creations, and window coverage.
Instructions
[READ] How long backups held a snapshot open on one VM, from task history.
Image-level backup products (Veeam, Commvault, Rubrik, NetBackup) snapshot the VM, copy the frozen disks, then delete the snapshot. vCenter records both ends, so the backup window is recoverable without credentials for the backup server.
This is a LOWER BOUND on the job, not its duration: work the product does
before the snapshot is taken and after it is removed is invisible to
vCenter. The returned basis says so — quote it alongside any figure.
Returns a rollup, not the list envelope: counts, four hour statistics
(backup_active / snapshot_present / total_window / snapshot_removal),
latest_cycle, longest_cycle, and unmatched rows for creations with no
removal (a backup that left its snapshot behind) or removals whose creation
predates the window.
Read two fields before reporting all-clear. history_unavailable non-null
means the history could not be read at all — that is not "no backups".
coverage_note non-null means vCenter has already expired part of the
requested window (task.maxAge — 30 days by default; the option is NOT
called vpxd.task.maxAge, which raises vim.fault.InvalidName), so the counts
describe a shorter period than days asked for. window_fully_covered
is the positive form: True when retention is at least days and nothing
in the window can have expired, so a VM whose oldest task is recent was
simply quiet; None when retention or the history could not be read.
An unmatched creation is not a failed backup. Each one carries status: "open", age_hours, this VM's longest_completed_cycle_hours and
possibly_in_progress — True while it is inside that VM's own observed
envelope, False past it, None when there is no completed cycle to compare
against. Do not report incomplete_cycles as failures without reading
those.
The creation task itself, during the seconds it executes, is absent
entirely: no completion time yet, so it forms neither a cycle nor an
unmatched row. A backup whose snapshot already exists is not this case —
that is the open cycle described above. So no open cycle does not prove no
backup is running.
Duplicate VM names raise rather than resolve to one, because a duration attributed to the wrong same-named VM looks exactly like a correct answer. For snapshots that exist right now use list_vm_snapshots or find_aging_snapshots.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | How far back to look, 1 to 365 (default 30). | |
| limit | No | Max cycle rows when include_cycles is set (capped at 200). | |
| target | No | vCenter/ESXi target from config (default if omitted). | |
| vm_name | Yes | Exact VM name; duplicates are refused, not guessed. | |
| include_cycles | No | Also return the individual cycles, newest kept on cap. |