> ## Documentation Index > Fetch the complete documentation index at: https://docs.runloop.ai/llms.txt > Use this file to discover all available pages before exploring further. # List Devboxes. > List all Devboxes while optionally filtering by status. ## OpenAPI ````yaml /openapi-specs/stainless-processed-openapi.json get /v1/devboxes openapi: 3.1.0 info: title: RunLoop API version: '0.1' description: >- The RunLoop API spec that allows you to host lambda functions and Devboxes to enable scaled long running ai workflows. contact: name: Runloop AI Support url: https://runloop.ai email: support@runloop.ai servers: - url: https://api.runloop.ai description: Runloop API variables: {} security: - bearerAuth: [] tags: - name: Benchmark - name: Blueprint - name: Blueprint-Lifecycle - name: Blueprint-ObservabilityTools - name: Devbox - name: Devbox-FileTools - name: Devbox-Lifecycle - name: Devbox-NetworkTools - name: Devbox-ObservabilityTools - name: Devbox-PersistenceTools - name: Devbox-ShellTools - name: Scenario - name: ScenarioScorer - name: accounts - name: agents - name: apikeys - name: axons - name: executions - name: gateway-configs - name: mcp-configs - name: network-policies - name: objects - name: restricted_keys - name: secrets - name: streaming paths: /v1/devboxes: get: tags: - Devbox summary: List Devboxes. description: List all Devboxes while optionally filtering by status. operationId: listDevboxes parameters: - name: status in: query description: Filter by status allowEmptyValue: true schema: $ref: '#/components/schemas/DevboxViewStatus' - name: limit in: query description: The limit of items to return. Default is 20. Max is 5000. allowEmptyValue: true schema: type: integer format: int32 - name: starting_after in: query description: >- Load the next page of data starting after the item with the given ID. allowEmptyValue: true schema: type: string - name: include_total_count in: query description: >- If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets. allowEmptyValue: true schema: type: boolean responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DevboxListView' x-codeSamples: - lang: JavaScript source: |- import Runloop from '@runloop/api-client'; const client = new Runloop({ bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const devboxView of client.devboxes.list()) { console.log(devboxView.id); } - lang: Python source: |- import os from runloop_api_client import Runloop client = Runloop( bearer_token=os.environ.get("RUNLOOP_API_KEY"), # This is the default and can be omitted ) page = client.devboxes.list() page = page.devboxes[0] print(page.id) components: schemas: DevboxViewStatus: type: string enum: - scheduled - provisioning - initializing - running - suspending - suspended - resuming - failure - shutdown description: > The status of the Devbox. scheduled: The Devbox is scheduled to run but infrastructure allocation has not started yet. 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. x-enum-descriptions: scheduled: >- The Devbox is scheduled to run but infrastructure allocation has not started yet. 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. DevboxListView: type: object properties: devboxes: type: array items: $ref: '#/components/schemas/DevboxView' description: List of devboxes matching filter. has_more: type: boolean total_count: format: int32 type: - integer - 'null' required: - devboxes - has_more DevboxView: type: object description: >- 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. properties: id: type: string description: The ID of the Devbox. name: description: The name of the Devbox. type: - string - 'null' status: $ref: '#/components/schemas/DevboxViewStatus' description: The current status of the Devbox. create_time_ms: type: integer format: int64 description: Creation time of the Devbox (Unix timestamp milliseconds). end_time_ms: format: int64 description: >- The time the Devbox finished execution (Unix timestamp milliseconds). Present if the Devbox is in a terminal state. type: - integer - 'null' initiator_type: $ref: '#/components/schemas/InitiatorType' description: The type of initiator that created the Devbox. initiator_id: description: The ID of the initiator that created the Devbox. type: - string - 'null' blueprint_id: description: >- The Blueprint ID used in creation of the Devbox, if the devbox was created from a Blueprint. type: - string - 'null' snapshot_id: description: >- The Snapshot ID used in creation of the Devbox, if the devbox was created from a Snapshot. type: - string - 'null' metadata: type: object additionalProperties: type: string description: The user defined Devbox metadata. failure_reason: description: >- The failure reason if the Devbox failed, if the Devbox has a 'failure' status. anyOf: - $ref: '#/components/schemas/DevboxViewFailureReason' - type: 'null' shutdown_reason: description: >- The shutdown reason if the Devbox shutdown, if the Devbox has a 'shutdown' status. anyOf: - $ref: '#/components/schemas/DevboxViewShutdownReason' - type: 'null' launch_parameters: $ref: '#/components/schemas/LaunchParameters' description: The launch parameters used to create the Devbox. capabilities: type: array items: $ref: '#/components/schemas/DevboxCapabilities' description: A list of capability groups this devbox has access to. state_transitions: type: array items: $ref: '#/components/schemas/DevboxStateTransition' description: A list of state transitions in order with durations tunnel: description: >- V2 tunnel information if a tunnel was created at launch time or via the createTunnel API. anyOf: - $ref: '#/components/schemas/TunnelView' - type: 'null' gateway_specs: additionalProperties: $ref: '#/components/schemas/GatewaySpecView' description: >- Gateway specifications configured for this devbox. Map key is the environment variable prefix (e.g., 'GWS_ANTHROPIC'). type: - object - 'null' mcp_specs: additionalProperties: $ref: '#/components/schemas/McpSpecView' description: >- [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. type: - object - 'null' required: - id - status - create_time_ms - end_time_ms - metadata - launch_parameters - capabilities - state_transitions InitiatorType: type: string enum: - unknown - api - scenario - scoring_validation - reflex DevboxViewFailureReason: type: string enum: - out_of_memory - out_of_disk - execution_failed - health_check_failed description: > 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. x-enum-descriptions: 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. DevboxViewShutdownReason: type: string enum: - api_shutdown - keep_alive_timeout - entrypoint_exit - idle - ttl_expired description: > 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. x-enum-descriptions: 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. LaunchParameters: type: object description: >- 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'. properties: launch_commands: items: type: string description: >- Set of commands to be run at launch time, before the entrypoint process is run. type: - array - 'null' resource_size_request: description: >- Preset Devbox resources (vCPU, RAM in GiB, ephemeral disk in GiB). If not set, SMALL is used. X_SMALL: 0.5 vCPU, 1 GiB RAM, 4 GiB disk. SMALL: 1 vCPU, 2 GiB RAM, 4 GiB disk. MEDIUM: 2 vCPU, 4 GiB RAM, 8 GiB disk. LARGE: 2 vCPU, 8 GiB RAM, 16 GiB disk. X_LARGE: 4 vCPU, 16 GiB RAM, 16 GiB disk. XX_LARGE: 8 vCPU, 32 GiB RAM, 16 GiB disk. CUSTOM_SIZE: set custom_cpu_cores, custom_gb_memory, and optionally custom_disk_size. anyOf: - $ref: '#/components/schemas/ResourceSize' - type: 'null' available_ports: items: type: integer format: int32 description: >- [Deprecated] A list of ports to make available on the Devbox. This field is ignored. type: - array - 'null' keep_alive_time_seconds: format: int64 description: >- Time in seconds after which Devbox will automatically shutdown. Default is 1 hour. Maximum is 48 hours (172800 seconds). type: - integer - 'null' after_idle: description: >- Configure Devbox lifecycle based on idle activity. If after_idle is set, Devbox will ignore keep_alive_time_seconds. If both after_idle and lifecycle.after_idle are set, they must have the same value. Use lifecycle.after_idle instead. anyOf: - $ref: '#/components/schemas/IdleConfigurationParameters' - type: 'null' custom_cpu_cores: format: int32 description: Custom CPU cores. Must be 0.5, 1, or a multiple of 2. Max is 16. type: - integer - 'null' custom_gb_memory: format: int32 description: >- Custom memory size in GiB. Must be 1 or a multiple of 2. Max is 64GiB. type: - integer - 'null' custom_disk_size: format: int32 description: >- Custom disk size in GiB. Must be a multiple of 2. Min is 2GiB, max is 64GiB. type: - integer - 'null' architecture: description: >- The target architecture for the Devbox. If unset, defaults to x86_64. anyOf: - $ref: '#/components/schemas/Architecture' - type: 'null' user_parameters: description: >- Specify the user for execution on Devbox. If not set, default `user` will be used. anyOf: - $ref: '#/components/schemas/UserParameters' - type: 'null' required_services: items: type: string description: >- A list of ContainerizedService names to be started when a Devbox is created. A valid ContainerizedService must be specified in Blueprint to be started. type: - array - 'null' network_policy_id: description: >- (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. type: - string - 'null' lifecycle: description: >- Lifecycle configuration for idle and resume behavior. Configure idle policy via lifecycle.after_idle (if both this and the top-level after_idle are set, they must match), resume triggers via lifecycle.resume_triggers, and optional lifecycle hooks via lifecycle.lifecycle_hooks. anyOf: - $ref: '#/components/schemas/LifecycleConfigurationParameters' - type: 'null' provisioning_tier: description: >- (Optional, Alpha) standard is default and flex is lazily provisioned and may be pre-empted. This is an alpha feature and its behavior may change without notice. anyOf: - $ref: '#/components/schemas/ProvisioningTier' - type: 'null' DevboxCapabilities: type: string enum: - unknown - docker_in_docker DevboxStateTransition: type: object properties: status: $ref: '#/components/schemas/DevboxViewStatus' transition_time_ms: $ref: '#/components/schemas/Number' description: The time the status change occurred TunnelView: type: object description: >- 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. Authenticated tunnels should pass auth_token as X-Runloop-Tunnel-Authorization: Bearer {auth_token}. properties: tunnel_key: type: string description: >- The encrypted tunnel key used to construct the tunnel URL. URL format: https://{port}-{tunnel_key}.tunnel.runloop.{domain} auth_mode: $ref: '#/components/schemas/TunnelAuthModeView' description: The authentication mode for the tunnel. auth_token: description: >- Bearer token for tunnel authentication. Only present when auth_mode is 'authenticated'. Pass as X-Runloop-Tunnel-Authorization: Bearer {auth_token}. type: - string - 'null' create_time_ms: type: integer format: int64 description: Creation time of the tunnel (Unix timestamp milliseconds). http_keep_alive: type: boolean description: >- When true, HTTP traffic through the tunnel counts as activity for idle lifecycle policies, resetting the idle timer. wake_on_http: type: boolean description: >- When true, HTTP traffic to a suspended devbox will automatically trigger a resume. required: - tunnel_key - auth_mode - create_time_ms - http_keep_alive - wake_on_http GatewaySpecView: type: object properties: gateway_config_id: type: string description: The ID of the gateway config (e.g., gwc_123abc). secret_id: type: string description: The ID of the secret containing the credential. required: - gateway_config_id - secret_id McpSpecView: type: object properties: mcp_config_id: type: string description: The ID of the MCP config (e.g., mcp_123abc). secret_id: type: string description: The ID of the secret containing the credential. required: - mcp_config_id - secret_id ResourceSize: type: string enum: - X_SMALL - SMALL - MEDIUM - LARGE - X_LARGE - XX_LARGE - CUSTOM_SIZE description: > 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. x-enum-descriptions: 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. IdleConfigurationParameters: type: object properties: idle_time_seconds: type: integer format: int32 description: After idle_time_seconds, on_idle action will be taken. on_idle: $ref: '#/components/schemas/IdleAction' description: Action to take after Devbox becomes idle. required: - idle_time_seconds - on_idle Architecture: type: string enum: - x86_64 - arm64 UserParameters: type: object description: Configuration for the Linux user in the Devbox environment. properties: username: type: string description: Username for the Linux user. uid: type: integer format: int32 description: User ID (UID) for the Linux user. Must be a non-negative integer. required: - username - uid LifecycleConfigurationParameters: type: object description: >- Lifecycle configuration for Devbox idle and resume behavior. Configure idle policy via after_idle, resume triggers via resume_triggers, and optional lifecycle hooks via lifecycle_hooks. properties: after_idle: description: >- Configure Devbox lifecycle based on idle activity. If both this and the top-level after_idle are set, they must have the same value. Prefer this field for new integrations. anyOf: - $ref: '#/components/schemas/IdleConfigurationParameters' - type: 'null' resume_triggers: description: Triggers that can resume a suspended Devbox. anyOf: - $ref: '#/components/schemas/ResumeTriggers' - type: 'null' lifecycle_hooks: description: >- Optional lifecycle hooks. suspend_commands run through the suspend path before the Devbox suspends; see launch_commands for work on every startup. anyOf: - $ref: '#/components/schemas/LifecycleHooks' - type: 'null' ProvisioningTier: type: string enum: - standard - flex Number: type: object properties: {} TunnelAuthModeView: type: string enum: - open - authenticated IdleAction: type: string enum: - shutdown - suspend description: | Action to take after Devbox idle timer is triggered. shutdown: Shutdown the Devbox. suspend: Suspend the Devbox. x-enum-descriptions: shutdown: Shutdown the Devbox. suspend: Suspend the Devbox. ResumeTriggers: type: object description: Triggers that can resume a suspended Devbox. properties: http: description: >- When true, HTTP traffic to a suspended Devbox via tunnel will trigger a resume. type: - boolean - 'null' axon_event: description: >- When true, axon events targeting a suspended Devbox will trigger a resume. type: - boolean - 'null' LifecycleHooks: type: object description: >- Lifecycle hooks for Devbox suspend. suspend_commands run sequentially as the configured Devbox user before the Devbox suspends; failures are logged but do not block suspending. The suspend_deadline_ms budget defaults to 30000 ms, may not exceed 60000 ms, and covers broker drain plus suspend_commands. If the deadline is exceeded, suspend work is abandoned, the timeout is logged, and the Devbox still proceeds to suspend. launch_commands still run on every startup, including after resume. properties: suspend_commands: items: type: string description: >- Commands to run through the suspend path before the Devbox suspends (e.g. cleanup, quiesce daemons). type: - array - 'null' suspend_deadline_ms: format: int64 description: >- Deadline in milliseconds for broker drain and suspend_commands during suspend. Defaults to 30000 ms and may not exceed 60000 ms. If exceeded, suspend work is abandoned, the timeout is logged, and the Devbox still proceeds to suspend by shutting down vmagent and killing the VM. type: - integer - 'null' securitySchemes: bearerAuth: scheme: bearer type: http ````