---
title: "Compare Runs"
method: GET
path: "/v1/runs/compare"
tags: ["Runs"]
---

# Compare Runs

`GET /v1/runs/compare`

## Request

- Base URL: `https://api.ensemble.markets` (the document declares no server; this is the origin it was published from)
- URL: `https://api.ensemble.markets/v1/runs/compare`
- Auth: HTTP bearer

Several of your runs side by side: the inputs that differ and the figures
a reader judges: model performance metrics.

The runs must be of one kind; they may belong to different programs.

## Query parameters

- `run_ids` string[], required: 2 to 8 runs of one kind

## Response `200`

Successful Response

- RunComparison: Several runs of one kind side by side.
  - `kind` 'model', required
  - `runs` Run[], required
    - `id` string, required: Run ID (run_... or legacy mr-/r-...). Read kind for the program type.
    - `kind` 'model', required
    - `program` RunProgramRef, required: The program a run belongs to.
      - `kind` 'model', required
      - `id` string, required
      - `name` string, nullable
      - `symbol` string, nullable
      - `slug` string, nullable
      - `inputs_schema` object, nullable: The program's declared inputs with defaults (on a single run read)
    - `status` 'queued' | 'running' | 'complete' | 'failed', required
    - `source` 'build' | 'manual' | 'scheduled' | 'cascade' | 'promote', required: build: the build's smoke run; manual: requested; scheduled: the nightly; cascade: a member changed; promote: after a promote
    - `label` string, nullable
    - `inputs` object, required
    - `is_default` boolean, required: Inputs equal the script's declared defaults
    - `intent` 'test' | 'refresh', nullable
    - `result_available` boolean: Whether the full result is retained and readable
    - `revision_id` string, nullable
    - `result_context` object, nullable: Execution-time strategy, input schema, display window and data provenance. Unknown legacy values are omitted, never borrowed from the current model.
    - `is_public` boolean
    - `live` boolean: This run's result is what the program serves
    - `data_as_of` string, nullable
    - `script_hash` string, nullable: SHA-256 of the script that ran; resolves to a build via getBuild
    - `summary` object, nullable: Headline figures, kept even when the full result is pruned
    - `usage` RunUsage
      - `units` integer, required
      - `base` integer, nullable
      - `seconds` integer, nullable
    - `estimate_cents` integer, nullable: On the response that queued this run: what it holds against the balance, in cents, until `usage` replaces it. Null on other reads.
    - `error` string, nullable
    - `duration_ms` integer, nullable
    - `created_at` string, date-time, required
    - `started_at` string, date-time, nullable
    - `completed_at` string, date-time, nullable
    - `result` object, nullable: With include=result: the model backtest history, including dates, returns, positions, targets and metadata.
    - `owner` RunOwner
      - `logo_url` string, nullable: Business branding, when the owner set a logo
    - `is_owner` boolean: True when the caller owns this run
  - `inputs_diff` InputsDiffRow[]: Inputs that differ across the runs
    - `key` string, required: Dotted path for nested inputs
    - `values` object, required: run_id -> value
  - `metrics` object: run_id -> model performance metrics over each stored run history
  - `period` object, nullable: Inclusive common start and end dates used for every compared metric
  - `dates` string[]: Common trading dates shared by the compared return series
  - `returns` object: run_id -> returns on the common dates
  - `unavailable_run_ids` string[]
  - `no_overlap` boolean

## Other responses

- `4XX`: The request was refused; `error.type` says why
- `5XX`: The server failed; quote `X-Request-Id` when reporting it

---

[API](https://skmtc.dev/ensemble/apis/ensemble-api.md) · [All operations](https://skmtc.dev/ensemble/apis/ensemble-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ensemble/apis/ensemble-api/revisions/4c0fbd80c197?raw)