Skip to navigation

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

The write answers with…It isWhat to do
202 Accepted and an operation_id (VM writes)AsynchronousPoll GET /compute/operations/{operation_id}
200 and a restore_id (snapshot and backup restores)AsynchronousPoll the restore’s status read
200 with a volume operation (Block Storage create, resize, delete)AsynchronousPoll the volume’s operations
A resource with a status or observed_state that isn’t final yet (networking, load balancers, Container Registry)AsynchronousPoll the resource itself
Anything else (Object Storage, CDN, Secret Manager, and most reads)SynchronousNothing: the change is done when the answer arrives

How it works

  1. Keep the identifier the response gives you (operation_id, restore_id, or the resource’s ID).
  2. Poll the status read until the state is terminal, meaning final: it won’t change again.
  3. Read the outcome. succeeded means the resource is in the state you asked for. failed, cancelled and timed_out come with an error code and message in the same response.
  4. 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-Key to 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_TOKEN and IBEE_WORKSPACE_ID set in your terminal, as in Make your first call.
  • jq to 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).

1

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:

op=$(curl -sS -X POST \
"https://api.ibee.ai/v1/compute/cloud-vms/VM_ID/actions/reboot?workspace_id=$IBEE_WORKSPACE_ID" \
-H "Authorization: Bearer $IBEE_TOKEN" \
-H "X-Idempotency-Key: $(uuidgen)" | jq -r '.operation_id')
echo "$op"

The API answers 202 Accepted with operation_id, vm_id, status and submitted_at.

2

Poll until the state is terminal

Read the operation every 5 seconds until its status is succeeded, failed, cancelled or timed_out:

while true; do
status=$(curl -sS "https://api.ibee.ai/v1/compute/operations/$op?workspace_id=$IBEE_WORKSPACE_ID" \
-H "Authorization: Bearer $IBEE_TOKEN" | jq -r '.status')
echo "$status"
case "$status" in succeeded|failed|cancelled|timed_out) break ;; esac
sleep 5
done
3

Check the result

On succeeded, read the VM (GET /compute/cloud-vms/VM_ID) to see its new status. On any other terminal state, read error_code and error_message from the operation.

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:

ToolChecks everyGives up waiting afterWhat happens then
Terraform provider2 seconds20 minutes (operation_timeout)The apply fails; the operation keeps running.

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}.

Write (cloud and GPU VMs)States while runningTerminal states
POST /compute/cloud-vms, POST /compute/gpu-vmsaccepted, running, waiting, compensatingsucceeded, failed, cancelled, timed_out
DELETE …/{vm_id}samesame
POST …/{vm_id}/actions/start, …/stop, …/rebootsamesame
PATCH …/{vm_id}/actions/accesssamesame
POST …/{vm_id}/actions/resizesamesame
POST …/{vm_id}/actions/attach-volume, …/detach-volumesamesame

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

WriteFollow withTerminal states
POST /compute/cloud-vm-snapshots/{snapshot_set_id}/actions/restoreGET /compute/cloud-vm-snapshots/restores/{restore_id}succeeded, failed, cancelled
POST /compute/gpu-vm-snapshots/{snapshot_set_id}/actions/restoreGET /compute/gpu-vm-snapshots/restores/{restore_id}same
POST /compute/cloud-vms/{vm_id}/backups/actions/restoreGET /compute/cloud-vm-backups/restores/{restore_id}same
POST /compute/gpu-vms/{vm_id}/backups/actions/restoreGET /compute/gpu-vm-backups/restores/{restore_id}same

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

WriteFollow withTerminal states
POST /block-storage/volumesGET /block-storage/volumes/{volume_id}/operationssucceeded, failed
POST /block-storage/volumes/{volume_id}/resizesamesame
DELETE /block-storage/volumes/{volume_id}same (the volume disappears when the delete succeeds)same

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

WriteFollow withStates
POST /container-registry/registriesGET /container-registry/registries/{registry_id}observed_state: PROVISIONING → ACTIVE or ERROR
DELETE /container-registry/registries/{registry_id}sameDELETING → DELETED (or 404)
POST …/{registry_id}/upgradeGET …/{registry_id}/packagepackage operation: PENDING → APPLIED or CANCELLED
POST …/{registry_id}/reconcileGET …/{registry_id}observed_state as above

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

You seeWhat it meansWhat to do
The operation stays accepted or running for a long timeThe work is still goingKeep polling. Giving up waiting doesn’t cancel it. If it never ends, contact support with the operation_id.
status: failed with error_codeThe work stopped. If the operation went through compensating, partial work was rolled back.Read error_message, fix the cause, then start a new write with a new idempotency key.
status: timed_outThe operation ran out of timeRead the resource to see its state, then start again if needed.
404 on GET /compute/operations/{operation_id}The operation wasn’t foundCheck the ID, and send the same workspace_id as the write.
409 on a VM writeThe request conflicts with the VM’s current stateRead the VM; if an operation is still running, wait for it to finish, then retry.
423 organization_suspendedWrites are refused while the organization is suspendedContact support.