Skip to navigation

Create a GPU VM snapshot

Creates a recovery snapshot of a GPU VM’s root disk, all attached disks, or selected data disks. Requires scope: vm.write.

# Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first).
# VM_ID: Virtual machine ID
curl -X POST "https://api.ibee.ai/v1/compute/gpu-vms/$VM_ID/snapshots?workspace_id=$WORKSPACE_ID" \
-H "Authorization: Bearer $IBEE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "<name>", "billing_catalog": {"sku_id": "<sku_id>", "sku_code": "<sku_code>"}}'

Authentication

AuthorizationBearer

IBEE platform API token. Production tokens start with ibee_prod_key_; development tokens start with ibee_dev_key_. Use a token only with its matching gateway environment.

Path parameters

vm_idstringRequired
Virtual machine ID.

Query parameters

workspace_idstringRequiredformat: "^[1-9][0-9]*$">=1 character

The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected.

Request

This endpoint expects an object.
namestringRequired1-255 characters
Display name for the snapshot set.
billing_catalogobjectRequired
Required. The snapshot storage SKU from the Billing catalog that the VM engine records for this snapshot. No public operation lists it yet.
descriptionstring or nullOptional<=1024 characters

Optional description (up to 1024 characters).

modeenumOptionalDefaults to all_attached

Which volumes to capture.

  • root_only: the root disk only.
  • all_attached: the root disk and every attached data volume (default).
  • selective: the root disk and the volumes in selected_data_volume_ids.
Allowed values:
selected_data_volume_idslist of stringsOptionalDefaults to []

Data volume IDs to include when mode is selective.

Response

Snapshot created or queued successfully.
organization_idstring
ID of the organization that owns the VM.
workspace_idstring
ID of the workspace the VM belongs to.
snapshot_set_idstring
Unique ID of the snapshot set.
vm_idstring
ID of the VM the snapshot was taken from.
namestring
Display name of the snapshot set.
recovery_point_idstring
Recovery point ID of this snapshot set.
statusenum

Lifecycle status of a backup run, snapshot set or restore.

  • queued: accepted and waiting to start.
  • running: in progress.
  • succeeded: finished; the recovery point is usable.
  • failed: stopped with an error (see error_message).
  • cancelled: stopped before it completed.
  • deleting: remote backup deletion is in progress; the run becomes unavailable after cleanup.
created_atdatetime

When the snapshot set was created (ISO 8601).

updated_atdatetime

When the snapshot set was last updated (ISO 8601).

organization_namestring or nullOptional
Display name of the owning organization, when the service has it.
workspace_namestring or nullOptional
Display name of the workspace, when the service has it.
vm_namestring or nullOptional
Display name of the VM at capture time.
vm_typeenumOptional

Kind of virtual machine.

  • cloud: general-purpose cloud VM.
  • gpu: VM with attached GPUs.
Allowed values:
descriptionstring or nullOptional
Description given at creation.
recovery_point_typeenumOptionalDefaults to snapshot

Always snapshot for a snapshot set.

Allowed values:
capture_scopeenumOptionalDefaults to all_attached

Which volumes the recovery point contains.

  • root_only: the root disk only.
  • all_attached: the root disk and every attached data volume.
  • selective: the root disk and the data volumes that were selected.
Allowed values:
captured_volume_countintegerOptionalDefaults to 1
Number of volumes in the snapshot set.
root_onlybooleanOptionalDefaults to true
True when only the root disk was captured.
size_gbinteger or nullOptional
Size of the captured data in GiB.
source_disk_size_gbinteger or nullOptional
Provisioned size of the source root disk in GiB at capture time.
display_size_gbinteger or nullOptional
Size in GiB as shown in the portal.
display_storage_bytesinteger or nullOptional

display_size_gb expressed in bytes.

backend_protected_storage_bytesinteger or nullOptional
Bytes of protected data as reported by the storage backend.
protected_storage_bytesinteger or nullOptional
Bytes of source data protected by this snapshot set.
billing_storage_bytesinteger or nullOptional
Bytes billed for storing this snapshot set.
billing_storage_sourcestringOptionalDefaults to unavailable

How billing_storage_bytes was obtained.

  • metered: measured in the backup store.
  • metered_from_manifest: summed from the volume manifest.
  • unavailable: not measured yet.
metering_statusstringOptionalDefaults to unavailable

metered once storage has been measured for billing; unavailable until then.

storage_backendstring or nullOptional
Identifier of the storage backend that holds the captured data.
captured_topology_hashstring or nullOptional

Hash of the VM’s volume layout at capture time; a different hash on the live VM means the layout drifted.

root_volume_idstring or nullOptional
ID of the captured root disk.
root_volume_namestring or nullOptional
Display name of the captured root disk.
volume_manifestlist of objectsOptional
One entry per captured volume.
volume_manifest_summaryobjectOptional
Short description of the volumes a recovery point contains.
live_drift_summaryobjectOptional
Difference between the volumes in a recovery point and the volumes attached to the VM now.
metadatamap from strings to anyOptional

Additional service-specific key-value data.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
413
Content Too Large Error
422
Unprocessable Entity Error
423
Locked Error
429
Too Many Requests Error
500
Internal Server Error
502
Bad Gateway Error
503
Service Unavailable Error
504
Gateway Timeout Error