---
title: "Wait for a Devbox to reach one of the specified statuses."
method: POST
path: "/v1/devboxes/{id}/wait_for_status"
tags: ["Devbox", "Devbox-Lifecycle"]
---

# Wait for a Devbox to reach one of the specified statuses.

`POST /v1/devboxes/{id}/wait_for_status`

Polls the Devbox's status until it reaches one of the desired statuses or times out.

## Path parameters

- `id` string, required

## Request body

- DevboxWaitForStatusRequest
  - `statuses` DevboxViewStatus[], 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.
  - `timeout_seconds` integer, nullable — (Optional) Timeout in seconds to wait for the status, up to 30 seconds. Defaults to 10 seconds.

## Response `200`

OK

- DevboxView — 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.
  - `name` string, nullable — The name of the Devbox.
  - `status` 'provisioning' | 'initializing' | 'running' | 'suspending' | 'suspended' | 'resuming' | 'failure' | 'shutdown', required — 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.
  - `create_time_ms` integer, required — Creation time of the Devbox (Unix timestamp milliseconds).
  - `end_time_ms` integer, nullable, required — The time the Devbox finished execution (Unix timestamp milliseconds). Present if the Devbox is in a terminal state.
  - `initiator_type` 'unknown' | 'api' | 'scenario' | 'scoring_validation'
  - `initiator_id` string, nullable — The ID of the initiator that created the Devbox.
  - `blueprint_id` string, nullable — The Blueprint ID used in creation of the Devbox, if the devbox was created from a Blueprint.
  - `snapshot_id` string, nullable — The Snapshot ID used in creation of the Devbox, if the devbox was created from a Snapshot.
  - `metadata` object, required — The user defined Devbox metadata.
  - `failure_reason` 'out_of_memory' | 'out_of_disk' | 'execution_failed' | 'health_check_failed' — The category of failure experienced by the Devbox. out_of_memory: The Devbox ran out of memory at runtime. Use launch parameters to request a larger resource size. out_of_disk: The Devbox ran out of disk at runtime. Please reach out to support for us to better support your use case. execution_failed: The Devbox failed at runtime. Please use the dashboard to look at the logs of the failure. health_check_failed: The Devbox failed its health checks. This may indicate resource utilization is close to the maximum. Consider requesting a larger resource size.
  - `shutdown_reason` 'api_shutdown' | 'keep_alive_timeout' | 'entrypoint_exit' | 'idle' | 'ttl_expired' — The reason that caused the transition of the Devbox to the shutown state. api_shutdown: The Devbox shutdown due to API request. entrypoint_exit: The Devbox entrypoint program completed. idle: The Devbox shutdown due to configured action on idle configuration. ttl_expired: The Devbox shutdown due to TTL expiration.
  - `launch_parameters` LaunchParameters, required — LaunchParameters enable you to customize the resources available to your Devbox as well as the environment set up that should be completed before the Devbox is marked as 'running'.
    - `launch_commands` string[], nullable — Set of commands to be run at launch time, before the entrypoint process is run.
    - `resource_size_request` 'X_SMALL' | 'SMALL' | 'MEDIUM' | 'LARGE' | 'X_LARGE' | 'XX_LARGE' | 'CUSTOM_SIZE' — The size of the Devbox resources for Runloop to allocate. X_SMALL: 0.5 cpu x 1GiB memory x 4GiB disk SMALL: 1 cpu x 2GiB memory x 4GiB disk MEDIUM: 2 cpu x 4GiB memory x 8GiB disk LARGE: 2 cpu x 8GiB memory x 16GiB disk X_LARGE: 4 cpu x 16GiB memory x 16GiB disk XX_LARGE: 8 cpu x 32GiB memory x 16GiB disk CUSTOM_SIZE: To choose a custom size, set this enum and also the custom_cpu_cores, custom_gb_memory, and optionally custom_disk_size in launch parameters. CPU must be 0.5, 1, or a multiple of 2 (max 16). Memory must be 1 or a multiple of 2 (max 64GiB). Disk must be a multiple of 2 (min 2GiB, max 64GiB). The cpu:memory ratio must be between 1:2 and 1:8 inclusive.
    - `available_ports` integer[], nullable — [Deprecated] A list of ports to make available on the Devbox. This field is ignored.
    - `keep_alive_time_seconds` integer, nullable — Time in seconds after which Devbox will automatically shutdown. Default is 1 hour. Maximum is 48 hours (172800 seconds).
    - `after_idle` IdleConfigurationParameters
      - `idle_time_seconds` integer, required — After idle_time_seconds, on_idle action will be taken.
      - `on_idle` 'shutdown' | 'suspend', required — Action to take after Devbox idle timer is triggered. shutdown: Shutdown the Devbox. suspend: Suspend the Devbox.
    - `custom_cpu_cores` integer, nullable — Custom CPU cores. Must be 0.5, 1, or a multiple of 2. Max is 16.
    - `custom_gb_memory` integer, nullable — Custom memory size in GiB. Must be 1 or a multiple of 2. Max is 64GiB.
    - `custom_disk_size` integer, nullable — Custom disk size in GiB. Must be a multiple of 2. Min is 2GiB, max is 64GiB.
    - `architecture` 'x86_64' | 'arm64'
    - `user_parameters` UserParameters — Configuration for the Linux user in the Devbox environment.
      - `username` string, required — Username for the Linux user.
      - `uid` integer, required — User ID (UID) for the Linux user. Must be a non-negative integer.
    - `required_services` string[], nullable — A list of ContainerizedService names to be started when a Devbox is created. A valid ContainerizedService must be specified in Blueprint to be started.
    - `network_policy_id` string, nullable — (Optional) ID of the network policy to apply to Devboxes launched with these parameters. When set on a Blueprint launch parameters, Devboxes created from it will inherit this policy unless explicitly overridden.
    - `lifecycle` LifecycleConfigurationParameters — Lifecycle configuration for Devbox idle and resume behavior. Configure idle policy via after_idle and resume triggers via resume_triggers.
      - `after_idle` IdleConfigurationParameters
        - `idle_time_seconds` integer, required — After idle_time_seconds, on_idle action will be taken.
        - `on_idle` 'shutdown' | 'suspend', required — Action to take after Devbox idle timer is triggered. shutdown: Shutdown the Devbox. suspend: Suspend the Devbox.
      - `resume_triggers` ResumeTriggers — Triggers that can resume a suspended Devbox.
        - `http` boolean, nullable — When true, HTTP traffic to a suspended Devbox via tunnel will trigger a resume.
        - `axon_event` boolean, nullable — When true, axon events targeting a suspended Devbox will trigger a resume.
  - `capabilities` DevboxCapabilities[], required — A list of capability groups this devbox has access to.
  - `state_transitions` DevboxStateTransition[], required — A list of state transitions in order with durations
    - `status` 'provisioning' | 'initializing' | 'running' | 'suspending' | 'suspended' | 'resuming' | 'failure' | 'shutdown' — 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.
    - `transition_time_ms` Number
  - `tunnel` TunnelView — A V2 tunnel provides secure HTTP access to services running on a Devbox. Tunnels allow external clients to reach web servers, APIs, or other HTTP services running inside a Devbox without requiring direct network access. Each tunnel is uniquely identified by an encrypted tunnel_key and can be configured for either open (public) or authenticated access. Usage: https://{port}-{tunnel_key}.tunnel.runloop.ai
    - `tunnel_key` string, required — The encrypted tunnel key used to construct the tunnel URL. URL format: https://{port}-{tunnel_key}.tunnel.runloop.{domain}
    - `auth_mode` 'open' | 'authenticated', required
    - `auth_token` string, nullable — Bearer token for tunnel authentication. Only present when auth_mode is 'authenticated'.
    - `create_time_ms` integer, required — Creation time of the tunnel (Unix timestamp milliseconds).
    - `http_keep_alive` boolean, required — When true, HTTP traffic through the tunnel counts as activity for idle lifecycle policies, resetting the idle timer.
    - `wake_on_http` boolean, required — When true, HTTP traffic to a suspended devbox will automatically trigger a resume.
  - `gateway_specs` object, nullable — Gateway specifications configured for this devbox. Map key is the environment variable prefix (e.g., 'GWS_ANTHROPIC').
  - `mcp_specs` object, nullable — [Beta] MCP specifications configured for this devbox. Map key is the environment variable name for the MCP token envelope. Each spec links an MCP config to a secret for MCP server access through the MCP hub.

## Other responses

- `400` — Invalid status provided.
- `404` — Devbox not found.
- `408` — Timeout waiting for status.

## Changes

- **2026-04-13** `5b536a11a713` — 1 info
  - added the optional property `launch_parameters/lifecycle/resume_triggers/axon_event` to the response with the `200` status
- **2026-04-10** `f0eb12cf4df4` — 1 warning
  - added the new `ttl_expired` enum value to the `shutdown_reason` response property for the response status `200`
- **2026-04-09** `a1c7e69cbbf7` — 3 info
  - added the optional property `launch_parameters/lifecycle` to the response with the `200` status
  - removed the `browser_usage` enum value from the `capabilities/items/` response property for the response status `200`
  - removed the `computer_usage` enum value from the `capabilities/items/` response property for the response status `200`
- **2026-04-03** `b0d4f639559e` — 1 warning
  - added the new `health_check_failed` enum value to the `failure_reason` response property for the response status `200`
- **2026-04-01** `c33fa67077f6` — 1 info
  - added the required property `tunnel/wake_on_http` to the response with the `200` status

[Full history](https://skmtc.dev/runloopai/apis/runloop-api/changes/v1/devboxes/:id/wait_for_status/post.md)

---

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