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

## Changes

- **2026-05-18** `722eb2b221c9` — 1 breaking, 1 info
  - removed the enum value `Template` from the `query` request parameter `state`
  - removed the `Template` enum value from the `state` response property for the response status `200`
- **2026-05-14** `d8b4e555ae63` — 1 warning, 1 info
  - added the new `Template` enum value to the `state` response property for the response status `200`
  - added the new enum value `Template` to the `query` request parameter `state`
- **2026-03-27** `a1912a634af4` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/kernel/apis/hypeman-api/changes/instances/:id/wait/get.md)

---

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