---
title: "Run Model"
method: POST
path: "/v1/models/{model}/runs"
tags: ["Models"]
---

# Run Model

`POST /v1/models/{model}/runs`

## 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/models/{model}/runs`
- Auth: HTTP bearer

Run the model's stored script (no generation).

Pass intent=test for an isolated result, even with default inputs; intent=refresh publishes approved defaults on success. Omission keeps the following legacy behavior for existing integrations. An empty body runs the declared defaults: that run is the live path, its result becomes what the model serves and cascades to the models that hold it. With `inputs`, unset keys take their defaults (see `inputs_schema`) and `from_run_id` starts from another run's inputs with `inputs` overlaid; unknown keys are rejected with the accepted keys named. Any run away from the defaults is a snapshot to compare, share or promote. `inputs.start_date` (YYYY-MM-DD) starts the backtest later than the data allows; earlier prices still feed lookbacks. Metered: one base unit plus one unit per second of sandbox time, charged once per run. 500 manual runs per account per day (429). Answers 202 with the queued run, or 200 with the finished run when `wait=true`. 409 `run_conflict` while a default run or a rebuild owns the model.

## Path parameters

- `model` string, required: Model ID (model_... or legacy m-...), slug, symbol or exact name

## Query parameters

- `wait` boolean: Block until the run finishes
- `include` string[]: result: the finished model run payload (with `wait=true`)

## Request body

- ModelRunRequest: Run the stored script. At default inputs the result becomes the live history. `inputs.start_date` (YYYY-MM-DD, before today) is the platform's input on every model: the engine trades nothing before it while earlier prices still feed lookbacks. Set it for a backtest that starts later than the data allows; such a run is a snapshot, never the live history.
  - `inputs` object: Values for the declared inputs; see `inputs_schema` on the program. If declared, universe is an ordered JSON array of ticker symbols and/or owned model IDs. Overrides create a snapshot; promote a successful run to change live defaults and dependencies.
  - `from_run_id` string, nullable: Start from this run's inputs (and settings); `inputs` overlay it
  - `label` string, nullable: A short name for the run, shown in lists and comparisons
  - `intent` 'test' | 'refresh', nullable: test never changes the current model, even at default inputs. refresh uses approved defaults and publishes on success. Omission retains the legacy input-equality behavior.

## 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)