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

id: string

Query ParametersExpand Collapse

state: "Created" or "Initializing" or "Running" or 5 more

Target state to wait for

Accepts one of the following:

"Created"

"Initializing"

"Running"

"Paused"

"Shutdown"

"Stopped"

"Standby"

"Unknown"

timeout: optional string

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

ReturnsExpand Collapse

WaitForStateResponse = object { state, timed_out, state_error }

state: "Created" or "Initializing" or "Running" or 5 more

Current instance state when the wait completed

Accepts one of the following:

"Created"

"Initializing"

"Running"

"Paused"

"Shutdown"

"Stopped"

"Standby"

"Unknown"

timed_out: boolean

Whether the timeout expired before the target state was reached

state_error: optional string

Error message when derived state is Unknown

Wait for instance to reach a target state

curl http://localhost:8080/instances/$ID/wait \
    -H "Authorization: Bearer $HYPEMAN_API_KEY"

{
  "state": "Created",
  "timed_out": true,
  "state_error": "state_error"
}

Returns Examples

{
  "state": "Created",
  "timed_out": true,
  "state_error": "state_error"
}