---
title: "Wait for instance to reach a target state"
method: GET
path: "/instances/{id}/wait"
---

# Wait for instance to reach a target state

`GET /instances/{id}/wait`

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

## Path parameters

- `id` string, required

## 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)
- `timeout` string

## Response `200`

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

- WaitForStateResponse
  - `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_error` string, nullable — Error message when derived state is Unknown
  - `timed_out` boolean, required — Whether the timeout expired before the target state was reached

## Other responses

- `400` — Invalid parameters
- `404` — Instance not found
- `500` — Internal server error

---

[API](https://skmtc.net/kernel/apis/hypeman-api.md) · [All operations](https://skmtc.net/kernel/apis/hypeman-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kernel/hypeman-api/versions/b4642bb950dc/schema)