---
title: "Promote Run"
method: POST
path: "/v1/runs/{run_id}/promote"
tags: ["Runs"]
---

# Promote Run

`POST /v1/runs/{run_id}/promote`

## 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/{run_id}/promote`
- Auth: HTTP bearer

Make a model run's inputs the script's defaults.

Queues a default run (source `promote`). For every model,
a successful candidate installs its INPUTS defaults, a `revision` build,
membership and depths. Verified results publish in the same transaction;
superseded results retain the prior allocations and queue a fresh run.
Execution failures preserve prior defaults and results. Required child
models settle before execution.
Successful live runs cascade to dependents. Answers 202 with that run, or 200 with it finished when
`wait=true`. Models only (409 `not_promotable` for other kinds); 409 when
the run is not complete, the script changed beyond INPUTS defaults, the
run already uses the defaults, or a default run is in flight. A run from
an earlier revision still promotes when the live script differs only in
those default literals.

## Path parameters

- `run_id` string, required: Run ID (run_... or legacy mr-/r-...). Use the returned ID; kind identifies the program type.

## Query parameters

- `wait` boolean: Block until the new default run finishes

## Response `200`

Completed inline (`wait=true`)

- Run: One model execution.
  - `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

## Other responses

- `202`: Successful Response
- `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)