Parameters
#computerstring
Computer name or ID.
computersstring[]
Computer names or IDs, supplied instead of
computer.namestring
Snapshot name of 1 to 63 lowercase letters, digits and hyphens. Start and end with a letter or digit. Omit to generate a name based on the current time.
notestring
One-line snapshot note of up to 200 bytes. An empty string clears it.
expiresstring
Snapshot retention in whole days from 1d to 365d, or never. Creation defaults to 7d. An edit without this field keeps the current expiry.
Returns
#dataobjectAlways present
A snapshot creation operation or per-Computer results.
Show 2 attributesHide attributes
alternative-1object
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.
alternative-2object
Results for a multi-Computer request. Each target can succeed or fail independently.
Show 2 attributesHide attributes
request_idstringAlways present
Request ID for this multi-Computer change.
resultsobject[] | nullAlways present
Each target's accepted operation, direct result or error, in request order.
Show 1 attributeHide attributes
itemsobject
One Computer's operation, direct result or error.
Show 4 attributesHide attributes
computerobjectAlways present
Target's ID and name.
Show 2 attributesHide attributes
idstringAlways present
Computer ID.
namestringAlways present
Computer's name when this result was prepared.
dataJSON value
Direct command result, with the same meaning as a single-Computer result. May be omitted.
errorobject
Reason this target could not be changed. May be omitted.
Show 7 attributesHide attributes
actionobject
A suggested command addressing the problem. May be omitted.
Show 2 attributesHide attributes
commandstringAlways present
Command's catalog name.
linestringAlways present
Complete suggested command line.
kindstringAlways present
Error category.
unknown means the effect is uncertain; reconcile before retrying.messagestringAlways present
What happened and any action needed from you.
operation_idstring
Operation to read before repeating uncertain work. May be omitted.
request_idstring
Request ID identifying the change during reconciliation. May be omitted.
retry_afterinteger
Seconds before retrying a rate-limited request or a refused wait. May be omitted.
urlstring
Payment page for a payment-required response. May be omitted.
operationobject
Accepted operation for this target, if the command returns one. May be omitted.
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".Errors
#| Code | Status | What happened |
|---|---|---|
| invalid | 400 | An input is missing or invalid. |
| unauthenticated | 401 | The credential is missing, invalid, expired or revoked. |
| denied | 403 | The caller lacks permission for this action. |
| not_found | 404 | The resource is absent or inaccessible to this caller. |
| conflict | 409 | The request conflicts with the current resource state or an earlier request. |
| over_capacity | 409 | The request exceeds a resource or credential allowance. |
| access_list_full | 409 | The change would exceed the access-list allowance. |
| payment_required | 402 | Payment or credit is required. |
| rate_limited | 429 | The caller's request rate exceeds its limit. |
| busy | 429 | Too much work is in progress to accept this request. |
| unknown | 503 | The outcome is unconfirmed; a change may have happened. |
| unavailable | 503 | The service or requested feature is unavailable. |
Notes
#- API key permission:
snapshot create. - Use
computersinstead ofcomputerfor several targets, each with its own result.