v33

latestOpenAPI 3.1.0raw.githubusercontent.com2026-04-175267122.5 KB

List instances

get/instances

Query parameters

Instance state:

Created: VMM created but not started (Cloud Hypervisor native)
Initializing: VM is running while guest init is still in progress
Running: Guest program has started and instance is ready
Paused: VM is paused (Cloud Hypervisor native)
Shutdown: VM shut down but VMM exists (Cloud Hypervisor native)
Stopped: No VMM running, no snapshot exists
Standby: No VMM running, snapshot exists (can be restored)
Unknown: Failed to determine state (see state_error for details)

Filter instances by state (e.g., Running, Stopped)

tagsobject

User-defined key-value tags.

Filter instances by tag key-value pairs. Uses deepObject style: ?tags[team]=backend&tags[env]=staging Multiple entries are ANDed together. All specified key-value pairs must match.

{
  "team": "backend",
  "env": "staging"
}

Response

List of instances

idstring required

Auto-generated unique identifier (CUID2 format)

namestring required

Human-readable name

imagestring required

OCI image reference

Instance state:

Created: VMM created but not started (Cloud Hypervisor native)
Initializing: VM is running while guest init is still in progress
Running: Guest program has started and instance is ready
Paused: VM is paused (Cloud Hypervisor native)
Shutdown: VM shut down but VMM exists (Cloud Hypervisor native)
Stopped: No VMM running, no snapshot exists
Standby: No VMM running, snapshot exists (can be restored)
Unknown: Failed to determine state (see state_error for details)

state_errorstring nullable

Error message if state couldn't be determined (only set when state is Unknown)

sizestring

Base memory size (human-readable)

hotplug_sizestring

Hotplug memory size (human-readable)

overlay_sizestring

Writable overlay disk size (human-readable)

vcpusinteger

Number of virtual CPUs

disk_io_bpsstring

Disk I/O rate limit (human-readable, e.g., "100MB/s")

envobject

Environment variables

tagsTags

User-defined key-value tags.

created_atstring date-time required

Creation timestamp (RFC3339)

started_atstring date-time nullable

Start timestamp (RFC3339)

stopped_atstring date-time nullable

Stop timestamp (RFC3339)

exit_codeinteger nullable

App exit code (null if VM hasn't exited)

exit_messagestring

Human-readable description of exit (e.g., "command not found", "killed by signal 9 (SIGKILL) - OOM")

has_snapshotboolean

Whether a snapshot exists for this instance

hypervisor'cloud-hypervisor' | 'firecracker' | 'qemu' | 'vz'

Hypervisor running this instance

Example response

[
  {
    "id": "tz4a98xxat96iws9zmbrgj3a",
    "name": "my-workload-1",
    "image": "docker.io/library/alpine:latest",
    "state_error": "failed to query VMM: connection refused",
    "size": "2GB",
    "hotplug_size": "2GB",
    "overlay_size": "10GB",
    "vcpus": 2,
    "disk_io_bps": "100MB/s",
    "tags": {
      "team": "backend",
      "env": "staging"
    },
    "network": {
      "enabled": true,
      "name": "default",
      "ip": "192.168.100.10",
      "mac": "02:00:00:ab:cd:ef",
      "bandwidth_download": "125MB/s",
      "bandwidth_upload": "125MB/s"
    },
    "volumes": [
      {
        "volume_id": "vol-abc123",
        "mount_path": "/mnt/data",
        "overlay_size": "1GB"
      }
    ],
    "gpu": {
      "profile": "L40S-1Q",
      "mdev_uuid": "aa618089-8b16-4d01-a136-25a0f3c73123"
    },
    "created_at": "2025-01-15T10:30:00Z",
    "started_at": "2025-01-15T10:30:05Z",
    "stopped_at": "2025-01-15T12:30:00Z",
    "exit_code": 137,
    "exit_message": "killed by signal 9 (SIGKILL)",
    "hypervisor": "cloud-hypervisor",
    "snapshot_policy": {
      "compression": {
        "enabled": true,
        "algorithm": "zstd",
        "level": 1
      },
      "standby_compression_delay": "2m"
    },
    "auto_standby": {
      "enabled": true,
      "idle_timeout": "5m",
      "ignore_source_cidrs": [
        "10.0.0.0/8",
        "192.168.0.0/16"
      ],
      "ignore_destination_ports": [
        22,
        9000
      ]
    }
  }
]