Skip to main content
POST
/
v1
/
devboxes
/
{id}
/
wait_for_status
Wait for a Devbox to reach one of the specified statuses.
curl --request POST \
  --url https://api.runloop.ai/v1/devboxes/{id}/wait_for_status \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "statuses": [
    "provisioning"
  ],
  "timeout_seconds": 123
}
'
{
  "id": "<string>",
  "status": "provisioning",
  "create_time_ms": 123,
  "end_time_ms": 123,
  "metadata": {},
  "launch_parameters": {
    "launch_commands": [
      "<string>"
    ],
    "resource_size_request": "X_SMALL",
    "keep_alive_time_seconds": 123,
    "available_ports": [
      123
    ],
    "after_idle": {
      "idle_time_seconds": 123,
      "on_idle": "shutdown"
    },
    "custom_cpu_cores": 123,
    "custom_gb_memory": 123,
    "custom_disk_size": 123,
    "architecture": "x86_64",
    "user_parameters": {
      "username": "<string>",
      "uid": 123
    },
    "required_services": [
      "<string>"
    ]
  },
  "capabilities": [
    "unknown"
  ],
  "state_transitions": [
    {
      "status": "provisioning",
      "transition_time_ms": {}
    }
  ],
  "name": "<string>",
  "initiator_type": "unknown",
  "initiator_id": "<string>",
  "blueprint_id": "<string>",
  "snapshot_id": "<string>",
  "failure_reason": "out_of_memory",
  "shutdown_reason": "api_shutdown"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
string
required

The Devbox ID.

Body

application/json
​
statuses
enum<string>[]
required

The Devbox statuses to wait for. At least one status must be provided. The devbox will be returned as soon as it reaches any of the provided statuses.

The status of the Devbox.

provisioning: Runloop is allocating and booting the necessary infrastructure resources. initializing: Runloop defined boot scripts are running to enable the environment for interaction. running: The Devbox is ready for interaction. suspending: The Devbox disk is being snapshotted as part of suspension. suspended: The Devbox disk is saved and no more active compute is being used for the Devbox. resuming: The Devbox disk is being loaded as part of booting a suspended Devbox. failure: The Devbox failed as part of booting or running user requested actions. shutdown: The Devbox was successfully shutdown and no more active compute is being used.

Available options:
provisioning,
initializing,
running,
suspending,
suspended,
resuming,
failure,
shutdown
​
timeout_seconds
integer<int32> | null

(Optional) Timeout in seconds to wait for the status, up to 30 seconds. Defaults to 10 seconds.

Response

OK

A Devbox represents a virtual development environment. It is an isolated sandbox that can be given to agents and used to run arbitrary code such as AI generated code.

​
id
string
required

The ID of the Devbox.

​
status
enum<string>
required

The current status of the Devbox.

Available options:
provisioning,
initializing,
running,
suspending,
suspended,
resuming,
failure,
shutdown
​
create_time_ms
integer<int64>
required

Creation time of the Devbox (Unix timestamp milliseconds).

​
end_time_ms
integer<int64> | null
required

The time the Devbox finished execution (Unix timestamp milliseconds). Present if the Devbox is in a terminal state.

​
metadata
object
required

The user defined Devbox metadata.

​
launch_parameters
object
required

The launch parameters used to create the Devbox.

​
capabilities
enum<string>[]
required

A list of capability groups this devbox has access to. This allows devboxes to be compatible with certain tools sets like computer usage APIs.

Available options:
unknown,
computer_usage,
browser_usage,
docker_in_docker
​
state_transitions
object[]
required

A list of state transitions in order with durations

​
name
string | null

The name of the Devbox.

​
initiator_type
enum<string>

The type of initiator that created the Devbox.

Available options:
unknown,
api,
scenario
​
initiator_id
string | null

The ID of the initiator that created the Devbox.

​
blueprint_id
string | null

The Blueprint ID used in creation of the Devbox, if the devbox was created from a Blueprint.

​
snapshot_id
string | null

The Snapshot ID used in creation of the Devbox, if the devbox was created from a Snapshot.

​
failure_reason
enum<string> | null

The failure reason if the Devbox failed, if the Devbox has a 'failure' status.

Available options:
out_of_memory,
out_of_disk,
execution_failed
​
shutdown_reason
enum<string> | null

The shutdown reason if the Devbox shutdown, if the Devbox has a 'shutdown' status.

Available options:
api_shutdown,
keep_alive_timeout,
entrypoint_exit,
idle