---
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
  - `idempotency_key` string, uuid
  - `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' | 'js_vitest' | 'python' | 'python_asv' | 'python_pytest' | 'ruby' | 'ruby_benchmark' | 'shell' | 'shell_hyperfine' | 'dart' | 'dart_benchmark_harness'
    - `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' | 'js_vitest' | 'python' | 'python_asv' | 'python_pytest' | 'ruby' | 'ruby_benchmark' | 'shell' | 'shell_hyperfine' | 'dart' | 'dart_benchmark_harness', required
  - `alerts` JsonAlert[], nullable — The report alerts. Omitted by default from the reports list endpoint; use the `expand` query param to include them.
    - `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
  - `counts` JsonReportCounts — Counts for a report.
    - `alerts` JsonReportAlertsCounts, required — Counts for the alerts of a report.
      - `active` integer, required — The number of active alerts.
      - `total` integer, required — The total number of alerts.
    - `results` JsonReportIterationCounts[], required — Counts for the report results, one entry per iteration.
      - `benchmarks` integer, required — The number of benchmarks in this iteration.
      - `measures` integer, required — The number of distinct measures in this iteration.
  - `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[], nullable — The report results, one list of results per iteration. Omitted by default from the reports list endpoint; use the `expand` query param to include them.
    - 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

---

[API](https://skmtc.net/bencherdev/apis/bencher-api.md) · [All operations](https://skmtc.net/bencherdev/apis/bencher-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bencherdev/bencher-api/revisions/84086e99e6cd/schema)