Skip to navigation

Start a cloud VM backup now

Queues a manual backup using the VM’s enabled backup policy. When billing_catalog is omitted, the policy’s stored catalog is used. Poll the returned run_id until the backup succeeds or fails. 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/cloud-vms/$VM_ID/backups/runs?workspace_id=$WORKSPACE_ID" \
-H "Authorization: Bearer $IBEE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"requested_by": "api", "reason": "<reason>"}'

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.
requested_bystringOptional1-128 charactersDefaults to api
reasonstring or nullOptional<=512 characters
billing_catalogobjectOptional
Optional override. When omitted, use the enabled policy's stored backup catalog.

Response

Backup queued.
organization_idstring
ID of the organization that owns the VM.
workspace_idstring
ID of the workspace the VM belongs to.
run_idstring
Unique ID of the backup run.
vm_idstring
ID of the VM that was backed up.
triggerenum

What started the run.

  • scheduled: the policy schedule.
  • manual: an on-demand request, from the portal or the API.
Allowed values:
backup_typeenum
  • full: a complete copy of the captured volumes.
  • incremental: only the changes since the previous run in the chain.
Allowed values:
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.
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.
source_run_idstring or nullOptional
ID of an earlier run this run derives from, when the service records one.
vm_backup_idstring or nullOptional
ID of the backup record in the backup store, when the service records one.
vm_typestring or nullOptionalDefaults to cloud

cloud or gpu. Default cloud.

vm_namestring or nullOptional
Display name of the VM at run time.
os_typestring or nullOptional

OS family of the VM (linux or windows) at run time.

os_distrostring or nullOptional
OS distribution of the VM at run time.
template_idstring or nullOptional
Template the VM was created from.
policy_idstring or nullOptional
Backup policy the run belongs to, when a policy created it.
chain_idstring or nullOptional

ID of the backup chain (a full backup and the incremental runs that follow it) the run belongs to.

recovery_point_idstring or nullOptional

Value to send as recovery_point_id when restoring from this run.

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

When the run started (ISO 8601); null while queued.

completed_atdatetime or nullOptional

When the run finished (ISO 8601); null until it does.

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.
bytes_transferredinteger or nullOptional
Bytes transferred to the backup store during the run.
backup_stored_size_bytesinteger or nullOptional
Bytes the backup occupies in the backup store.
backup_stored_size_gbdouble or nullOptional

backup_stored_size_bytes expressed in GiB.

protected_storage_bytesinteger or nullOptional
Bytes of source data protected by this recovery point.
billing_storage_bytesinteger or nullOptional
Bytes billed for storing this recovery point.
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.

captured_volume_countintegerOptionalDefaults to 1
Number of volumes in the recovery point.
root_onlybooleanOptionalDefaults to true
True when only the root disk was captured.
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.

capture_scopeenum or nullOptional

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:
recovery_point_typeenumOptionalDefaults to backup

Always backup for a backup run.

Allowed values:
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.
error_messagestring or nullOptional

Error detail when status is failed.

metadatamap from strings to anyOptional

Additional service-specific key-value data.

Errors

401
Unauthorized 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