Skip to navigation
API ReferenceCloud VMs

List cloud VMs

Returns one page of cloud VMs in the workspace, newest first: 10 by default, at most 100 per page. Use limit and offset to page through the rest. Requires scope: vm.read.

# Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first).
curl "https://api.ibee.ai/v1/compute/cloud-vms?workspace_id=$WORKSPACE_ID" \
  -H "Authorization: Bearer $IBEE_API_TOKEN"

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.

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.

limitintegerOptional1-100Defaults to 10

Maximum number of records to return. The server returns 10 when this is omitted; use offset to read further pages.

offsetintegerOptional>=0Defaults to 0
Number of records to skip before the first one returned.
searchstringOptional1-120 characters
Return only VMs whose name, IP address, OS or plan contains this text.
sort_byenumOptionalDefaults to created_at

Field to sort by. Default created_at.

Allowed values:
sort_directionenumOptionalDefaults to desc

Sort direction. Default desc.

Allowed values:
statusenumOptional

Send all to include VMs deleted in the selected month (see date).

Allowed values:
datestringOptionalformat: "^[0-9]{4}-[0-9]{2}$"

Calendar month YYYY-MM for the deleted-VM history returned with status=all.

Response

Cloud VMs returned successfully.
idstringOptional
Unique VM ID.
namestringOptional
Display name of the VM.
statusenumOptional

Lifecycle status of the VM.

  • pending: create accepted, not started yet.
  • creating, provisioning: compute, disk and network resources are being allocated.
  • configuring: the guest is being configured (keys, network, cloud-init).
  • running: powered on.
  • starting: a start is in progress.
  • stopping: a stop is in progress.
  • stopped: powered off.
  • rebooting: a reboot is in progress.
  • resizing, resizing_plan, resizing_disk: a CPU/memory or root-disk change is being applied.
  • attaching_volume, detaching_volume: a block volume is being attached or detached.
  • deleting: a delete is in progress.
  • deleted: the VM no longer exists.
  • error: the last operation failed; see the operation or events for detail.
cpuintegerOptional
vCPUs.
ram_mbintegerOptional
Memory in MB.
disk_gbintegerOptional
Root disk size in GB.
os_typestringOptional

OS family: linux or windows.

os_distrostringOptional

OS distribution, for example ubuntu.

plan_namestring or nullOptional
Name of the compute plan the VM runs on.
public_ipstring or nullOptional

Public IPv4 address; null when the VM has none.

private_ipstring or nullOptional

Private IPv4 address; null when none is assigned.

tagslist of stringsOptional
Tags given at creation.
created_atdatetimeOptional

When the VM was created (ISO 8601).

updated_atdatetime or nullOptional

When the VM record was last changed (ISO 8601).

Errors

401
Unauthorized Error
403
Forbidden Error
503
Service Unavailable Error