--- title: "Create a run" method: POST path: "/v0/run" tags: ["run", "reports"] --- # Create a run `POST /v0/run` Create a run. The user does not need have an account yet or be authenticated. The project may or may not exist yet. ## Request body - JsonNewRun - `branch` string - `context` RunContext - `end_time` string, date-time, required - `hash` string - `job` JsonNewRunJob — Job configuration for a remote runner execution. Sent as part of `JsonNewRun` when the CLI `--image` flag is used. The API server uses this to create a job for a bare metal runner instead of expecting locally-executed benchmark results. - `allow_failure` boolean, nullable — Allow benchmark failure without short-circuiting iterations - `backdate` string, date-time - `build_time` boolean, nullable — Track the build time of the benchmark command - `cmd` string[], nullable — Command override (like Docker CMD) - `entrypoint` string[], nullable — Container entrypoint override (like Docker ENTRYPOINT) - `env` object, nullable — Environment variables passed to the container - `file_paths` string[], nullable — File paths to collect from the VM after job completion - `file_size` boolean, nullable — Track the file size of the output files instead of parsing their contents - `image` string, required - `iter` integer - `spec` string - `timeout` integer - `project` string - `results` string[], required — An array of benchmarks results in Bencher Metric Format (BMF). - `settings` JsonReportSettings - `adapter` 'magic' | 'json' | 'rust' | 'rust_bench' | 'rust_criterion' | 'rust_iai' | 'rust_gungraun' | 'cpp' | 'cpp_google' | 'cpp_catch2' | 'go' | 'go_bench' | 'java' | 'java_jmh' | 'c_sharp' | 'c_sharp_dot_net' | 'js' | 'js_benchmark' | 'js_time' | 'python' | 'python_asv' | 'python_pytest' | 'ruby' | 'ruby_benchmark' | 'shell' | 'shell_hyperfine' - `average` 'mean' | 'median' - `fold` 'min' | 'max' | 'mean' | 'median' - `spec_reset` boolean, nullable — When set to `true`, clear the hardware spec from the testbed. - `start_point` JsonUpdateStartPoint - `branch` string - `clone_thresholds` boolean, nullable — If set to `true`, the thresholds from the start point branch will be deep copied to the branch. This can be useful for pull request branches that should have the same thresholds as their target branch. Requires the `branch` field to be set. - `hash` string - `max_versions` integer, nullable — The maximum number of historical branch versions to include. Versions beyond this number will be omitted. The default is 255. Requires the `branch` field to be set. - `reset` boolean, nullable — Reset the branch head to an empty state. If the start point `branch` is specified, the new branch head will begin at that start point. Otherwise, the branch head will be reset to an empty state. - `start_time` string, date-time, required - `testbed` string - `thresholds` JsonReportThresholds - `models` object, nullable — Map of measure UUID, slug, or name to the threshold model to use. If a measure name or slug is provided, the measure will be created if it does not exist. - `reset` boolean, nullable — Reset all thresholds for the branch and testbed. Any models present in the `models` field will still be updated accordingly. If a threshold already exists and is not present in the `models` field, its current model will be removed. ## Response `201` successful creation - JsonReport - `adapter` 'magic' | 'json' | 'rust' | 'rust_bench' | 'rust_criterion' | 'rust_iai' | 'rust_gungraun' | 'cpp' | 'cpp_google' | 'cpp_catch2' | 'go' | 'go_bench' | 'java' | 'java_jmh' | 'c_sharp' | 'c_sharp_dot_net' | 'js' | 'js_benchmark' | 'js_time' | 'python' | 'python_asv' | 'python_pytest' | 'ruby' | 'ruby_benchmark' | 'shell' | 'shell_hyperfine', required - `alerts` JsonAlert[], required - `benchmark` JsonBenchmark, required - `archived` string, date-time - `created` string, date-time, required - `modified` string, date-time, required - `name` string, required - `project` string, uuid, required - `slug` string, required - `uuid` string, uuid, required - `boundary` JsonBoundary, required - `baseline` number, double, nullable - `lower_limit` number, double, nullable - `upper_limit` number, double, nullable - `created` string, date-time, required - `iteration` integer, required - `limit` 'lower' | 'upper', required - `metric` JsonMetric, required - `lower_value` number, double, nullable - `upper_value` number, double, nullable - `uuid` string, uuid, required - `value` number, double, required - `modified` string, date-time, required - `report` string, uuid, required - `status` union, required - 'active' — The alert is active. - 'dismissed' — The alert has been dismissed by a user. - 'silenced' — The alert has been silenced by the system. - `threshold` JsonThreshold, required - `branch` JsonBranch, required - `archived` string, date-time - `created` string, date-time, required - `head` JsonHead, required - `created` string, date-time, required - `replaced` string, date-time - `start_point` JsonStartPoint - `branch` string, uuid, required - `head` string, uuid, required - `version` JsonVersion, required - … - `uuid` string, uuid, required - `version` JsonVersion - `hash` string - `number` integer, required - `modified` string, date-time, required - `name` string, required - `project` string, uuid, required - `slug` string, required - `uuid` string, uuid, required - `created` string, date-time, required - `measure` JsonMeasure, required - `archived` string, date-time - `created` string, date-time, required - `modified` string, date-time, required - `name` string, required - `project` string, uuid, required - `slug` string, required - `units` string, required - `uuid` string, uuid, required - `model` JsonModel - `created` string, date-time, required - `lower_boundary` number, double - `max_sample_size` integer - `min_sample_size` integer - `replaced` string, date-time - `test` 'static' | 'percentage' | 'z_score' | 't_test' | 'log_normal' | 'iqr' | 'delta_iqr', required - `upper_boundary` number, double - `uuid` string, uuid, required - `window` integer - `modified` string, date-time, required - `project` string, uuid, required - `testbed` JsonTestbed, required - `archived` string, date-time - `created` string, date-time, required - `modified` string, date-time, required - `name` string, required - `project` string, uuid, required - `slug` string, required - `spec` JsonSpec — A hardware spec - `architecture` 'x86_64' | 'aarch64', required - `archived` string, date-time - `cpu` integer, required - `created` string, date-time, required - `disk` integer, required - `fallback` string, date-time - `memory` integer, required - `modified` string, date-time, required - `name` string, required - `network` boolean, required - `os` 'linux' | 'macos' | 'windows', required - `sandbox` 'firecracker' - `slug` string, required - `uuid` string, uuid, required - `uuid` string, uuid, required - `uuid` string, uuid, required - `uuid` string, uuid, required - `branch` JsonBranch, required - `archived` string, date-time - `created` string, date-time, required - `head` JsonHead, required - `created` string, date-time, required - `replaced` string, date-time - `start_point` JsonStartPoint - `branch` string, uuid, required - `head` string, uuid, required - `version` JsonVersion, required - `hash` string - `number` integer, required - `uuid` string, uuid, required - `version` JsonVersion - `hash` string - `number` integer, required - `modified` string, date-time, required - `name` string, required - `project` string, uuid, required - `slug` string, required - `uuid` string, uuid, required - `created` string, date-time, required - `end_time` string, date-time, required - `job` string, uuid - `project` JsonProject, required - `claimed` string, date-time - `created` string, date-time, required - `modified` string, date-time, required - `name` string, required - `organization` string, uuid, required - `slug` string, required - `url` string - `uuid` string, uuid, required - `visibility` 'public' | 'private', required - `results` array[], required - JsonReportResult[] - `benchmark` JsonBenchmark, required - `archived` string, date-time - `created` string, date-time, required - `modified` string, date-time, required - `name` string, required - `project` string, uuid, required - `slug` string, required - `uuid` string, uuid, required - `iteration` integer, required - `measures` JsonReportMeasure[], required - `boundary` JsonBoundary - `baseline` number, double, nullable - `lower_limit` number, double, nullable - `upper_limit` number, double, nullable - `measure` JsonMeasure, required - `archived` string, date-time - `created` string, date-time, required - `modified` string, date-time, required - `name` string, required - `project` string, uuid, required - `slug` string, required - `units` string, required - `uuid` string, uuid, required - `metric` JsonMetric, required - `lower_value` number, double, nullable - `upper_value` number, double, nullable - `uuid` string, uuid, required - `value` number, double, required - `threshold` JsonThresholdModel - `created` string, date-time, required - `model` JsonModel, required - `created` string, date-time, required - `lower_boundary` number, double - `max_sample_size` integer - `min_sample_size` integer - `replaced` string, date-time - `test` 'static' | 'percentage' | 'z_score' | 't_test' | 'log_normal' | 'iqr' | 'delta_iqr', required - `upper_boundary` number, double - `uuid` string, uuid, required - `window` integer - `project` string, uuid, required - `uuid` string, uuid, required - `start_time` string, date-time, required - `testbed` JsonTestbed, required - `archived` string, date-time - `created` string, date-time, required - `modified` string, date-time, required - `name` string, required - `project` string, uuid, required - `slug` string, required - `spec` JsonSpec — A hardware spec - `architecture` 'x86_64' | 'aarch64', required - `archived` string, date-time - `cpu` integer, required - `created` string, date-time, required - `disk` integer, required - `fallback` string, date-time - `memory` integer, required - `modified` string, date-time, required - `name` string, required - `network` boolean, required - `os` 'linux' | 'macos' | 'windows', required - `sandbox` 'firecracker' - `slug` string, required - `uuid` string, uuid, required - `uuid` string, uuid, required - `user` JsonPubUser - `name` string, required - `slug` string, required - `uuid` string, uuid, required - `uuid` string, uuid, required ## Other responses - `4XX` — Error - `5XX` — Error ## Changes - **2026-03-23** `1634d744359e` — 4 info - added the optional property `alerts/items/threshold/testbed/spec/allOf[#/components/schemas/JsonSpec]/sandbox` to the response with the `201` status - added the optional property `testbed/spec/allOf[#/components/schemas/JsonSpec]/sandbox` to the response with the `201` status - added the required property `alerts/items/threshold/testbed/spec/allOf[#/components/schemas/JsonSpec]/os` to the response with the `201` status - added the required property `testbed/spec/allOf[#/components/schemas/JsonSpec]/os` to the response with the `201` status - **2026-03-20** `36c8ad753527` — 5 breaking, 3 warning, 3 info - removed the enum value `dart` of the request property `settings/allOf[#/components/schemas/JsonReportSettings]/adapter/allOf[#/components/schemas/Adapter]/` - removed the enum value `dart_benchmark_harness` of the request property `settings/allOf[#/components/schemas/JsonReportSettings]/adapter/allOf[#/components/schemas/Adapter]/` - removed the enum value `js_vitest` of the request property `settings/allOf[#/components/schemas/JsonReportSettings]/adapter/allOf[#/components/schemas/Adapter]/` - removed the required property `alerts/items/threshold/testbed/spec/allOf[#/components/schemas/JsonSpec]/os` from the response with the `201` status - …7 more [Change history](https://skmtc.dev/bencherdev/apis/bencher-api/changes/v0/run/post.md) --- [API](https://skmtc.dev/bencherdev/apis/bencher-api.md) · [All operations](https://skmtc.dev/bencherdev/apis/bencher-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bencherdev/bencher-api/revisions/1634d744359e/schema)