Skip to content

List or read snapshots

List Computer snapshots or read one snapshot's details. Use the snapshot's name or ID to restore its disk or make a copy.

Parameters

#
computerstring
Computer name or ID. Omit to list snapshots across your Computers.
snapshotstring
Snapshot name or ID within the named Computer.
sortstring
Order for a snapshot list. Give size for largest first. Omit for newest first.
limitstring
Maximum snapshots per page. MCP defaults to 100. Use the returned next value with after for more matches.
afterstring
Snapshot ID to list after in the current sort order. Use the previous page's next value.

Returns

#
dataobjectAlways present
Snapshots and their storage measurements, or one named snapshot.
Show 2 attributesHide attributes
alternative-1object
Visible snapshots and their latest storage measurements.
Show 7 attributesHide attributes
computersobject[] | nullAlways present
Storage that deleting each Computer's snapshots would free: on a page, the Computers of its snapshots.
Show 1 attributeHide attributes
itemsobject
Storage recoverable by deleting a Computer's snapshots together.
Show 3 attributesHide attributes
idstringAlways present
Computer ID.
namestringAlways present
Computer name.
snapshot_bytesstring | nullAlways present
Bytes freed by deleting all this Computer's snapshots, as a decimal string; null if unknown.
nextstring
The after of the next page. Absent on the last page. May be omitted.
observed_atstring (date-time) | nullAlways present
Time of the storage observation, or null when unknown.
poolsobject[] | nullAlways present
Storage use in the pools you can read.
Show 1 attributeHide attributes
itemsobject
A pool's included and used storage. Byte counts are decimal strings; null measurements are unknown.
Show 5 attributesHide attributes
allowance_bytesstring | nullAlways present
Included storage for files and snapshots, in bytes.
files_bytesstring | nullAlways present
Storage used by files, in bytes.
idstringAlways present
Pool ID.
snapshot_bytesstring | nullAlways present
Storage used by snapshots, in bytes.
used_bytesstring | nullAlways present
Files and snapshots together, in bytes.
snapshotsobject[] | nullAlways present
Snapshots matching the request.
Show 1 attributeHide attributes
itemsobject
A point-in-time disk snapshot. Byte counts are decimal strings; null measurements are unknown.
Show 21 attributesHide attributes
automaticbooleanAlways present
Whether Heaven created the snapshot automatically.
changed_since_bytesstring | nullAlways present
Bytes changed since this snapshot.
computerobjectAlways present
Computer whose disk was snapshotted.
Show 2 attributesHide attributes
idstringAlways present
Referenced object's stable ID.
namestringAlways present
Referenced object's name.
copiesobject[] | nullAlways present
Accessible Computers originating from this snapshot, including those later reset or restored.
Show 1 attributeHide attributes
itemsobject
A Computer, pool or snapshot reference.
Show 2 attributesHide attributes
idstringAlways present
Referenced object's stable ID.
namestringAlways present
Referenced object's name.
created_byobjectAlways present
Who requested the snapshot.
Show 2 attributesHide attributes
emailstring | nullAlways present
Their email address, or null when none is available.
user_idstringAlways present
Person's user ID.
data_bytesstring | nullAlways present
Reported snapshot data, in bytes.
data_sourcestring | nullAlways present
Where the data-size measurement came from.
disk_bytesstring | nullAlways present
Logical disk size at capture, in bytes.
expires_atstring (date-time) | nullAlways present
When the snapshot expires. Null keeps it until explicitly deleted.
idstringAlways present
Snapshot ID.
kept_byobject[] | nullAlways present
Snapshots retaining this deleted snapshot. Null unless dependencies delay deletion.
Show 1 attributeHide attributes
itemsobject
A Computer, pool or snapshot reference.
Show 2 attributesHide attributes
idstringAlways present
Referenced object's stable ID.
namestringAlways present
Referenced object's name.
kept_by_computersobject[] | nullAlways present
Accessible copied Computers whose disks still retain this deleted snapshot's data.
Show 1 attributeHide attributes
itemsobject
A Computer, pool or snapshot reference.
Show 2 attributesHide attributes
idstringAlways present
Referenced object's stable ID.
namestringAlways present
Referenced object's name.
kept_by_other_copiesinteger
Number of copied Computers you cannot access that retain this snapshot. May be omitted.
namestringAlways present
Snapshot's name within its Computer.
notestringAlways present
Saved note about this snapshot.
observed_atstring (date-time) | nullAlways present
Time the measurements were last reported.
requested_atstring (date-time)Always present
When snapshot creation was requested.
savedstring | nullAlways present
Disk capture method: stopped, flushed or unflushed. Flushing does not guarantee application consistency. Null means capture is unreported.
size_bytesstring | nullAlways present
Storage unique to this snapshot, in bytes.
statestringAlways present
Snapshot lifecycle state. pending awaits disk capture.
taken_atstring (date-time) | nullAlways present
When the disk snapshot was taken, or null before it has been reported.
stalebooleanAlways present
Whether the measurements are too old to treat as current.
totalintegerAlways present
How many snapshots the list holds, on every page.
alternative-2object
The selected snapshot.
Show 1 attributeHide attributes
snapshotobjectAlways present
Selected snapshot.
Show 21 attributesHide attributes
automaticbooleanAlways present
Whether Heaven created the snapshot automatically.
changed_since_bytesstring | nullAlways present
Bytes changed since this snapshot.
computerobjectAlways present
Computer whose disk was snapshotted.
Show 2 attributesHide attributes
idstringAlways present
Referenced object's stable ID.
namestringAlways present
Referenced object's name.
copiesobject[] | nullAlways present
Accessible Computers originating from this snapshot, including those later reset or restored.
Show 1 attributeHide attributes
itemsobject
A Computer, pool or snapshot reference.
Show 2 attributesHide attributes
idstringAlways present
Referenced object's stable ID.
namestringAlways present
Referenced object's name.
created_byobjectAlways present
Who requested the snapshot.
Show 2 attributesHide attributes
emailstring | nullAlways present
Their email address, or null when none is available.
user_idstringAlways present
Person's user ID.
data_bytesstring | nullAlways present
Reported snapshot data, in bytes.
data_sourcestring | nullAlways present
Where the data-size measurement came from.
disk_bytesstring | nullAlways present
Logical disk size at capture, in bytes.
expires_atstring (date-time) | nullAlways present
When the snapshot expires. Null keeps it until explicitly deleted.
idstringAlways present
Snapshot ID.
kept_byobject[] | nullAlways present
Snapshots retaining this deleted snapshot. Null unless dependencies delay deletion.
Show 1 attributeHide attributes
itemsobject
A Computer, pool or snapshot reference.
Show 2 attributesHide attributes
idstringAlways present
Referenced object's stable ID.
namestringAlways present
Referenced object's name.
kept_by_computersobject[] | nullAlways present
Accessible copied Computers whose disks still retain this deleted snapshot's data.
Show 1 attributeHide attributes
itemsobject
A Computer, pool or snapshot reference.
Show 2 attributesHide attributes
idstringAlways present
Referenced object's stable ID.
namestringAlways present
Referenced object's name.
kept_by_other_copiesinteger
Number of copied Computers you cannot access that retain this snapshot. May be omitted.
namestringAlways present
Snapshot's name within its Computer.
notestringAlways present
Saved note about this snapshot.
observed_atstring (date-time) | nullAlways present
Time the measurements were last reported.
requested_atstring (date-time)Always present
When snapshot creation was requested.
savedstring | nullAlways present
Disk capture method: stopped, flushed or unflushed. Flushing does not guarantee application consistency. Null means capture is unreported.
size_bytesstring | nullAlways present
Storage unique to this snapshot, in bytes.
statestringAlways present
Snapshot lifecycle state. pending awaits disk capture.
taken_atstring (date-time) | nullAlways present
When the disk snapshot was taken, or null before it has been reported.

Errors

#
CodeStatusWhat happened
invalid400An input is missing or invalid.
unauthenticated401The credential is missing, invalid, expired or revoked.
denied403The caller lacks permission for this action.
not_found404The resource is absent or inaccessible to this caller.
conflict409The request conflicts with the current resource state or an earlier request.
over_capacity409The request exceeds a resource or credential allowance.
access_list_full409The change would exceed the access-list allowance.
rate_limited429The caller's request rate exceeds its limit.
busy429Too much work is in progress to accept this request.
unknown503The outcome is unconfirmed; a change may have happened.
unavailable503The service or requested feature is unavailable.

Notes

#
  • API key permission: snapshot view.