Asynchronous operations
An asynchronous operation is a request that answers as soon as IBEE has accepted the work, before the work is finished. Creating a VM, for example, answers straight away, while the VM itself is still being built. The answer gives you an ID; you read that ID’s status until it says the work is over. This is called polling.
Most writes are not like this: they finish before they answer. This page lists every write that doesn’t, the read that reports its progress, and the states that mean the work is over.
When to use polling
How it works
- Keep the identifier the response gives you (
operation_id,restore_id, or the resource’s ID). - Poll the status read until the state is terminal, meaning final: it won’t change again.
- Read the outcome.
succeededmeans the resource is in the state you asked for.failed,cancelledandtimed_outcome with an error code and message in the same response. - If your own client times out before a terminal state, read the status again. For a lost VM create response, repeat the identical body with the original
X-Idempotency-Keyto recover the same operation. Keep the key while the outcome is uncertain; a new key starts a separate create.
Before you begin
- An API token with the read scope for the product you poll, for example Virtual Machines → Read (
vm.read) for VM operations. Writing needs the write scope; reading the status needs only read. See Authentication. IBEE_TOKENandIBEE_WORKSPACE_IDset in your terminal, as in Make your first call.jqto pick fields out of JSON, for the example below.
Follow a VM operation
This example reboots a VM and waits until the reboot is over. Replace VM_ID with one of your VM IDs (GET /compute/cloud-vms lists them).
Start the write
VM writes need an X-Idempotency-Key header: a unique string per action that lets the API recognise a repeated request (see Idempotency). Save the operation_id from the answer:
The API answers 202 Accepted with operation_id, vm_id, status and submitted_at.
With the CLI, the write prints the operation_id and ibee ops get OPERATION_ID reads it; repeat it as in the loop above. The CLI page has the same loop using ibee ops get.
How long to wait
IBEE doesn’t publish how long each operation takes; it depends on the product, the size and the location. Terraform waits for you:
The SDKs and the CLI don’t wait: they return the operation_id at once and you poll. Giving up waiting never cancels the work. Polling every 2 to 5 seconds is enough; honour Retry-After on a 429.
Compute operations
Every VM write below answers 202 Accepted with an OperationAccepted body that carries operation_id and vm_id. Follow it with GET /compute/operations/{operation_id}.
The operation’s action names the work (create, start, stop, reboot, delete, resize, attach_volume, detach_volume, update_access; the field can also read resize_plan, resize_root_disk, snapshot, restore, rebuild or rescue), current_step says where it is, and error_code plus error_message explain a failure. compensating means a failed step is being rolled back; wait for the terminal state before acting.
The VM itself reports its own status on GET …/{vm_id} (pending, creating, provisioning, configuring, running, starting, stopping, stopped, rebooting, resizing, attaching_volume, detaching_volume, deleting, deleted, error). Use the operation to know when a request is done, and the VM status to know what the VM is doing now.
These writes take an X-Idempotency-Key header. Poll a known operation. A timeout or gateway error can leave a create outcome uncertain; recover it using the identical body and original key. An explicit admission refusal can be corrected before retrying.
Snapshot and backup restores
A restore answers 200 with restore_id and status: queued; it then moves through running. With target_mode: new_vm the response’s target_vm_id names the VM being built; with replace the source VM is rebuilt in place; with volume_only a detached volume is created.
Snapshot create (POST …/{vm_id}/snapshots) answers when the snapshot set exists; its status on GET /compute/cloud-vm-snapshots/{snapshot_set_id} tells you when it is usable.
Manual backups, deletion and queued cancellation
With an enabled policy, POST /compute/cloud-vms/{vm_id}/backups/runs (or the GPU
VM equivalent) returns 200 with run_id and status: queued. Omit
billing_catalog to reuse the enabled policy’s stored backup selection. Use
GET /compute/plans/backup-storage when selecting the catalog for the policy.
Poll GET /compute/cloud-vm-backups/runs/{run_id} (or gpu-vm-backups) until the
run reports succeeded, failed or cancelled. Backups disabled or another
queued/running run return 409 before a new run is created.
DELETE /compute/cloud-vm-backups/runs/{run_id} (or its GPU equivalent) answers
202 with status: deleting. Poll that run until GET returns 404; a repeated
delete then returns 404 too.
The run lists return only finished, successful runs (and any being deleted), so read a
run by ID to see whether it is queued, running or failed. For a scheduled run, the
backup policy’s last_status shows how the latest finished run ended.
A queued backup restore can be cancelled with
POST /compute/cloud-vm-backups/restores/{restore_id}/actions/cancel (or the GPU
VM equivalent). It returns the cancelled restore. An already running restore is
refused with 409; cancellation does not stop a running restore.
Block storage
Each volume operation carries operation (create, attach, detach, resize, delete), status (in-progress, succeeded, failed), the idempotency_key it was created with, and error on failure. Attach and detach are VM actions and report through the compute operation above.
Container registry
desired_state is what you asked for; observed_state is what the service has reached. They agree when observed_generation equals generation.
Networking resources
VPCs, subnets, NAT gateways (which let private VMs reach the internet through a shared public IP) and port-forwarding rules answer with the resource and a status field: provisioning while the network is being set up, available when it is ready, deleting while it is removed, and error with an error_message. Poll the resource’s own read (GET /networking/vpcs/{vpc_id} and so on). Load balancers have their own status read, GET /networking/load-balancers/{load_balancer_id}/status.
Everything else
CDN and Secret Manager writes are synchronous: when the response arrives, the change is made. So are Object Storage writes, once its management resumes. A 423 means the organization is suspended and writes are refused; it is not a temporary state, so don’t retry it.
Troubleshooting
Related pages
- API overview: idempotency keys and every error code
- Get operation status in the reference
- Rate limits: polling without hitting
429 - CLI:
ibee ops getand exit codes
