--- title: "Start a new ScenarioRun." method: POST path: "/v1/scenarios/start_run" tags: ["Scenario"] --- # Start a new ScenarioRun. `POST /v1/scenarios/start_run` Start a new ScenarioRun based on the provided Scenario. ## Request body - StartScenarioRunParameters - `scenario_id` string, required — ID of the Scenario to run. - `run_name` string, nullable — Display name of the run. - `benchmark_run_id` string, nullable — Benchmark to associate the run. - `metadata` object, nullable — User defined metadata to attach to the run for organization. - `runProfile` RunProfile - `purpose` string, nullable — Purpose of the run. - `envVars` object, nullable — Mapping of Environment Variable to Value. May be shown in devbox logging. Example: {"DB_PASS": "DATABASE_PASSWORD"} would set the environment variable 'DB_PASS' to the value 'DATABASE_PASSWORD_VALUE'. - `secrets` object, nullable — Mapping of Environment Variable to User Secret Name. Never shown in devbox logging. Example: {"DB_PASS": "DATABASE_PASSWORD"} would set the environment variable 'DB_PASS' to the value of the secret 'DATABASE_PASSWORD'. - `launchParameters` 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. These must be int values that are a multiple of 2 with a cpu:memory ratio between 2 and 8 inclusive. Min/Max permitted cpu cores, memory, and disk size are 1/16, 2/64, and 2/64 respectively. - `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). - `available_ports` integer[], nullable — A list of ports to make available on the Devbox. Only ports made available will be surfaced to create tunnels via the 'createTunnel' API. - `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 resource size, number of cpu cores, must be multiple of 2. Min is 1, max is 16. - `custom_gb_memory` integer, nullable — custom memory size, number in GiB, must be a multiple of 2. Min is 2GiB, max is 64GiB. - `custom_disk_size` integer, nullable — custom disk size, number 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. - `mounts` Mount[], nullable — A list of mounts to be included in the scenario run. - union - ObjectMount - `object_id` string, required — The ID of the object to write. - `object_path` string, required — The path to write the object on the Devbox. Use absolute path of object (ie /home/user/object.txt, or directory if archive /home/user/archive_dir) - `type` 'object_mount', required - AgentMount - `agent_id` string, nullable, required — The ID of the agent to mount. Either agent_id or name must be set. - `agent_name` string, nullable, required — The name of the agent to mount. Returns the most recent agent with a matching name if no agent id string provided. Either agent id or name must be set - `agent_path` string, nullable — Path to mount the agent on the Devbox. Required for git and object agents. Use absolute path (e.g., /home/user/agent) - `auth_token` string, nullable — Optional auth token for private repositories. Only used for git agents. - `type` 'agent_mount', required - CodeMount - `repo_name` string, required — The name of the repo to mount. By default, code will be mounted at /home/user/{repo_name}s. - `repo_owner` string, required — The owner of the repo. - `install_command` string, nullable — Installation command to install and setup repository. - `token` string, nullable — The authentication token necessary to pull repo. - `type` 'code_mount', required - FileMount - `target` string, required — Target path where the file should be mounted. - `content` string, required — Content of the file to mount. - `type` 'file_mount', required ## Response `200` OK - ScenarioRunView — A ScenarioRunView represents a single run of a Scenario on a Devbox. When completed, the ScenarioRun will contain the final score and output of the run. - `id` string, required — ID of the ScenarioRun. - `name` string, nullable — Optional name of ScenarioRun. - `scenario_id` string, required — ID of the Scenario that has been run. - `devbox_id` string, required — ID of the Devbox on which the Scenario is running. - `benchmark_run_id` string, nullable — ID of the BenchmarkRun that this Scenario is associated with, if any. - `scoring_contract_result` ScoringContractResultView — A ScoringContractResultView represents the result of running all scoring functions on a given input context. - `score` number, float, required — Total score for all scoring contracts. This will be a value between 0 and 1. - `scoring_function_results` ScoringFunctionResultView[], required — List of all individual scoring function results. - `score` number, float, required — Final score for the given scoring function. - `scoring_function_name` string, required — Scoring function name that ran. - `output` string, required — Log output of the scoring function. - `state` 'unknown' | 'complete' | 'error', required - `start_time_ms` integer — The time that the scenario started - `duration_ms` integer, nullable — Duration scenario took to run. - `state` 'running' | 'scoring' | 'scored' | 'completed' | 'canceled' | 'timeout' | 'failed', required - `metadata` object, required — User defined metadata to attach to the scenario run for organization. - `purpose` string, nullable — Purpose of the ScenarioRun. - `environment_variables` object, nullable — Environment variables used to run the scenario. - `secrets_provided` object, nullable — User secrets used to run the scenario. ## Changes - **2026-01-19** `8ebd9dbfacb1` — 1 info - added the new optional request property `runProfile/launchParameters/network_policy_id` - **2025-12-13** `370a5d676ff0` — 1 info - added the new optional request property `runProfile/mounts` [Change history](https://skmtc.dev/runloopai/apis/runloop-api/changes/v1/scenarios/start_run/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/eac4defbf398/schema)