---
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. 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 positive 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.

## Response `200`

OK

- BenchmarkRunView — A BenchmarkRunView represents a run of a complete set of Scenarios, organized under a Benchmark.
  - `id` string, required — The ID of the BenchmarkRun.
  - `benchmark_id` string, required — The ID of the Benchmark.
  - `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', 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/5f33221208c1/schema)