v41

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-055374134.9 KB

Get instance details

get/instances/{id}

Path parameters

idstring required

Instance ID or name

Response

Instance details

idstring required

Auto-generated unique identifier (CUID2 format)

namestring required

Human-readable name

imagestring required

OCI image reference

platformstring

Resolved image platform as os/arch[/variant] (e.g. "linux/amd64"). amd64 images on an arm64 host run under Rosetta emulation.

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

phase_durations_msobject

Cumulative milliseconds the instance has spent in each lifecycle phase, including time accrued in the current phase up to the response time. Keys mirror instance states lowercased (running, standby, paused, stopped, created, initializing, shutdown). Consumers (e.g. billing) sum the phases they consider billable.

current_phasestring

The lifecycle phase the instance is currently in.

current_phase_sincestring date-time

When the instance entered current_phase.

Example response

{
  "id": "tz4a98xxat96iws9zmbrgj3a",
  "name": "my-workload-1",
  "image": "docker.io/library/alpine:latest",
  "platform": "linux/amd64",
  "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
    ]
  },
  "health_check": {
    "interval": "10s",
    "timeout": "2s",
    "start_period": "30s",
    "failure_threshold": 3,
    "success_threshold": 1,
    "http": {
      "port": 8080,
      "path": "/healthz",
      "scheme": "http",
      "expected_status": 200
    },
    "tcp": {
      "port": 5432
    },
    "exec": {
      "command": [
        "curl",
        "-f",
        "http://localhost:4318/"
      ],
      "working_dir": "/app"
    }
  },
  "health_status": {
    "status": "healthy",
    "consecutive_successes": 4,
    "last_checked_at": "2026-05-16T01:00:00Z",
    "last_success_at": "2026-05-16T01:00:00Z",
    "last_failure_at": "2026-05-16T00:59:50Z",
    "last_error": "connection refused"
  },
  "restart_policy": {
    "policy": "on_failure",
    "backoff": "5s",
    "max_attempts": 10,
    "stable_after": "10m"
  },
  "restart_status": {
    "attempts": 3,
    "last_attempt_at": "2025-01-15T12:30:00Z",
    "next_attempt_at": "2025-01-15T12:30:05Z",
    "blocked_reason": "max_attempts_exceeded",
    "last_reason": "health_check_failed"
  },
  "phase_durations_ms": {
    "running": 60000,
    "standby": 300000
  },
  "current_phase": "running",
  "current_phase_since": "2026-05-11T14:00:00Z"
}