---
title: "Start a new BenchmarkRun."
method: POST
path: "/v1/benchmarks/start_run"
tags: ["Benchmark"]
---

# Start a new BenchmarkRun.

`POST /v1/benchmarks/start_run`

Start a new BenchmarkRun based on the provided Benchmark.

## Request body

- StartBenchmarkRunParameters
  - `benchmark_id` string, required — ID of the Benchmark to run.
  - `run_name` string, nullable — Display name of the run.
  - `metadata` object, nullable — User defined metadata to attach to the benchmark 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. 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, resume triggers via resume_triggers, and optional lifecycle hooks via lifecycle_hooks.
        - `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.
        - `lifecycle_hooks` LifecycleHooks — 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.
          - `suspend_commands` string[], nullable — Commands to run through the suspend path before the Devbox suspends (e.g. cleanup, quiesce daemons).
          - `suspend_deadline_ms` integer, nullable — 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.
      - `provisioning_tier` 'standard' | 'flex'
    - `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}.
          - `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.
          - `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
        - BrokerMount
          - `axon_id` string, required — The ID of the axon event stream to mount onto the Devbox.
          - `protocol` 'acp' | 'claude_json' | 'codex_json' | 'pi_json'
          - `agent_binary` string, nullable — Binary to launch the agent (e.g., 'opencode'). Used by protocols that launch a subprocess (acp, claude_json, codex_json, pi_json).
          - `working_directory` string, nullable — Working directory in which to launch the agent binary. Defaults to the home directory if not specified.
          - `launch_args` string[], nullable — Arguments to pass to the agent command (e.g., ['acp']). Used by protocols that launch a subprocess (acp, claude_json, codex_json, pi_json).
          - `type` 'broker_mount', required

## Response `200`

OK

- BenchmarkRunView — A BenchmarkRunView represents a run of a complete set of Scenarios, organized under a Benchmark or created by a BenchmarkJob.
  - `id` string, required — The ID of the BenchmarkRun.
  - `benchmark_id` string, nullable — The ID of the Benchmark definition. Present if run was created from a benchmark definition.
  - `name` string, nullable — The name of the BenchmarkRun.
  - `start_time_ms` integer, required — The time the benchmark run execution started (Unix timestamp milliseconds).
  - `duration_ms` integer, nullable — The duration for the BenchmarkRun to complete.
  - `state` 'running' | 'canceled' | 'completed' | 'failed', required
  - `score` number, float, nullable — The final score across the BenchmarkRun, present once completed. Calculated as sum of scenario scores / number of scenario runs.
  - `metadata` object, required — User defined metadata to attach to the benchmark run for organization.
  - `purpose` string, nullable — Purpose of the run.
  - `environment_variables` object, nullable — Environment variables used to run the benchmark.
  - `secrets_provided` object, nullable — User secrets used to run the benchmark. Example: {"DB_PASS": "DATABASE_PASSWORD"} would set the environment variable 'DB_PASS' on all scenario devboxes to the value of the secret 'DATABASE_PASSWORD'.

---

[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/e9dc776053e4/schema)