KEkernel

Wait for instance to reach a target state

Changed on

Blocks until the instance reaches the specified target state, the timeout expires, or the instance enters a terminal/error state. Useful for avoiding client-side polling when waiting for state transitions (e.g. waiting for an instance to become Running).

get/instances/{id}/wait

Request

  • Base URL
    http://localhost:4973
  • URL
    http://localhost:4973/instances/{id}/wait
  • Auth
    HTTP bearer

Path parameters

idstring required

Instance ID or name

Query parameters

state'Created' | 'Initializing' | 'Running' | 'Paused' | 'Shutdown' | 'Stopped' | 'Standby' | 'Unknown' required

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)

Target state to wait for

timeoutstring

Maximum duration to wait (Go duration format, e.g. "30s", "2m"). Capped at 5 minutes. Defaults to 60 seconds.

Response

Wait completed (target state reached, timed out, or terminal state detected)

state'Created' | 'Initializing' | 'Running' | 'Paused' | 'Shutdown' | 'Stopped' | 'Standby' | 'Unknown' required

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 when derived state is Unknown

timed_outboolean required

Whether the timeout expired before the target state was reached

Changes

  • 722eb2b221c9Revision changes
    • breaking

      removed the enum value Template from the query request parameter state

    • info

      removed the Template enum value from the response property for the response status

  • d8b4e555ae63Revision changes
    • warning

      added the new Template enum value to the response property for the response status

    • info

      added the new enum value Template to the query request parameter state