---
title: "List Blueprints."
method: GET
path: "/v1/blueprints"
tags: ["Blueprint"]
---

# List Blueprints.

`GET /v1/blueprints`

List all Blueprints or filter by name.

## Query parameters

- `name` string
- `status` string
- `limit` integer
- `starting_after` string
- `include_total_count` boolean

## Response `200`

OK

- BlueprintListView
  - `blueprints` BlueprintView[], required — List of blueprints matching filter.
    - `id` string, required — The id of the Blueprint.
    - `name` string, required — The name of the Blueprint.
    - `status` 'queued' | 'provisioning' | 'building' | 'failed' | 'build_complete', required — The status of the Blueprint build. queued: Blueprint is queued waiting for build capacity to become available. provisioning: Allocating and booting the necessary infrastructure resources to create the Blueprint image. building: Building the Blueprint image. failed: Blueprint image failed to build. See the logs on the dashboard. build_complete: Blueprint image completed build. You can now use the ID to create Devboxes.
    - `state` 'created' | 'deleted', required
    - `create_time_ms` integer, required — Creation time of the Blueprint (Unix timestamp milliseconds).
    - `build_finish_time_ms` integer, nullable — Build completion time of the Blueprint (Unix timestamp milliseconds).
    - `parameters` BlueprintBuildParameters, required
      - `name` string, required — Name of the Blueprint.
      - `dockerfile` string, nullable — Dockerfile contents to be used to build the Blueprint.
      - `system_setup_commands` string[], nullable — A list of commands to run to set up your system.
      - `code_mounts` CodeMountParameters[], nullable — A list of code mounts to be included in the Blueprint.
        - `repo_name` string, required — The name of the repo to mount. By default, code will be mounted at /home/user/{repo_name}.
        - `repo_owner` string, required — The owner of the repo.
        - `install_command` string, nullable — Installation command to install and setup repository.
        - `git_ref` string, nullable — Optional git ref (branch or tag) to checkout. Defaults to the repository default branch.
        - `token` string, nullable — The authentication token necessary to pull repo.
      - `launch_parameters` LaunchParameters — 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.
      - `file_mounts` object, nullable — (Optional) Map of paths and file contents to write before setup.
      - `base_blueprint_id` string, nullable — (Optional) ID of previously built blueprint to use as a base blueprint for this build.
      - `base_blueprint_name` string, nullable — (Optional) Name of previously built blueprint to use as a base blueprint for this build. When set, this will load the latest successfully built Blueprint with the given name. Only one of (base_blueprint_id, base_blueprint_name) should be specified.
      - `services` ContainerizedServiceView[], nullable — (Optional) List of containerized services to include in the Blueprint. These services will be pre-pulled during the build phase for optimized startup performance.
        - `name` string, required — The name of the container service.
        - `image` string, required — The image of the container service.
        - `credentials` Credentials
          - `username` string, required — The username of the container service.
          - `password` string, required — The password of the container service.
        - `env` object, nullable — The environment variables of the container service.
        - `port_mappings` string[], nullable — The port mappings of the container service. Port mappings are in the format of <host_port>:<container_port>.
        - `options` string, nullable — Additional Docker container create options.
      - `metadata` object, nullable — (Optional) User defined metadata for the Blueprint.
      - `build_args` object, nullable — (Optional) Arbitrary Docker build args to pass during build.
      - `secrets` object, nullable — (Optional) Map of mount IDs/environment variable names to secret names. Secrets will be available to commands during the build. Secrets are NOT stored in the blueprint image. Example: {"DB_PASS": "DATABASE_PASSWORD"} makes the secret 'DATABASE_PASSWORD' available as environment variable 'DB_PASS'.
      - `build_context` BuildContext — A build context backed by an Object.
        - `object_id` string, required — The ID of an object, whose contents are to be used as a build context.
        - `type` 'object', required
      - `network_policy_id` string, nullable — (Optional) ID of the network policy to apply during blueprint build. This restricts network access during the build process. This does not affect devboxes created from this blueprint; if you want devboxes created from this blueprint to inherit the network policy, set the network_policy_id on the blueprint launch parameters.
    - `failure_reason` 'out_of_memory' | 'out_of_disk' | 'build_failed' — The cause of the failure of the Blueprint build. out_of_memory: The build has run out of memory. Contact support if this is unexpected. out_of_disk: The build has run out of disk. Contact support if this is unexpected. build_failed: The build has failed. Use the dashboard to look at Blueprint build logs for more info.
    - `base_blueprint_id` string, nullable — The ID of the base Blueprint.
    - `containerized_services` ContainerizedServiceView[], nullable — List of ContainerizedServices available in the Blueprint. Services can be explicitly started when creating a Devbox.
      - `name` string, required — The name of the container service.
      - `image` string, required — The image of the container service.
      - `credentials` Credentials
        - `username` string, required — The username of the container service.
        - `password` string, required — The password of the container service.
      - `env` object, nullable — The environment variables of the container service.
      - `port_mappings` string[], nullable — The port mappings of the container service. Port mappings are in the format of <host_port>:<container_port>.
      - `options` string, nullable — Additional Docker container create options.
    - `is_public` boolean — Whether this Blueprint is publicly accessible to all users.
    - `metadata` object, nullable — User defined metadata associated with the blueprint.
    - `devbox_capabilities` DevboxCapabilities[], nullable — Capabilities that will be available on Devbox.
  - `has_more` boolean, required
  - `total_count` integer, nullable

## Changes

- **2026-04-13** `5b536a11a713` — 1 info
  - added the optional property `blueprints/items/parameters/launch_parameters/lifecycle/resume_triggers/axon_event` to the response with the `200` status
- **2026-04-09** `a1c7e69cbbf7` — 4 info
  - added the optional property `blueprints/items/parameters/code_mounts/items/git_ref` to the response with the `200` status
  - added the optional property `blueprints/items/parameters/launch_parameters/lifecycle` to the response with the `200` status
  - removed the `browser_usage` enum value from the `blueprints/items/devbox_capabilities/items/` response property for the response status `200`
  - removed the `computer_usage` enum value from the `blueprints/items/devbox_capabilities/items/` response property for the response status `200`
- **2026-03-24** `32e4b2dfb757` — 1 warning, 1 info
  - removed the optional property `remaining_count` from the response with the `200` status
  - added the new optional `query` request parameter `include_total_count`
- **2026-02-19** `8704a652545c` — 4 breaking
  - the response property `remaining_count` became nullable for the status `200`
  - the response property `total_count` became nullable for the status `200`
  - the response property `remaining_count` became optional for the status `200`
  - the response property `total_count` became optional for the status `200`
- …earlier changes not shown

[Full history](https://skmtc.dev/runloopai/apis/runloop-api/changes/v1/blueprints/get.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)