Skip to content

Change a snapshot

Change a Computer snapshot's name, note or expiry.

Parameters

#
computerstringRequired
Computer name or ID.
snapshotstringRequired
Snapshot name or ID.
namestring
Replacement name of 1 to 63 lowercase letters, digits and hyphens. Start and end with a letter or digit.
notestring
One-line snapshot note of up to 200 bytes. An empty string clears it.
expiresstring
New retention measured from the time of editing, from 1d to 365d or never. Omit to keep the current expiry.

Returns

#
dataobjectAlways present
A snapshot record and its creation or edit operation.
Show 3 attributesHide attributes
operationobjectAlways present
Snapshot operation as last read.
Show 9 attributesHide attributes
bystring
Requester's email address, or user ID if no email is recorded. Omitted for your own requests. May be omitted.
completed_atstring (date-time)
When the operation reached its final state. Absent while unfinished. May be omitted.
computer_idstringAlways present
Computer's stable ID.
created_atstring (date-time)
When Heaven accepted the change. May be omitted.
error_codestring
Recorded failure code. May be omitted.
idstringAlways present
Operation ID for operation view.
kindstringAlways present
Change being tracked.
messagestring
An explanation of the recorded failure and any next action. May be omitted.
statestringAlways present
accepted means saved and unfinished. complete means the change finished. failed means it could not finish. superseded means a newer change replaced it before completion. Values: "accepted", "complete", "failed", "superseded".
request_idstringAlways present
Request ID for this snapshot change.
snapshotobjectAlways present
Snapshot's current record.
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.
payment_required402Payment or credit is required.
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 edit.