Skip to content

run_model

Use run_model for run.py. Pass a relative path; bare names resolve from the repo root before legacy model/, and nested paths end in .py. Choose sync for short runs or async for longer ones; set outputs_preview=true only for useful bounded detail, then poll with get_run.

NameTypeRequiredDefaultDescription
modeAnnotated[Literal['sync', 'async'], Field(description='Run synchronously or queue asynchronously.')]Yes—
model_nameAnnotated[str, Field(description='Name of the Bridge Town model to execute.')]Yes—
path`Annotated[strNone, Field(description=“Python file to execute relative to the model repository, instead of run.py. Bare script names may omit ‘.py’ and resolve at the repository root first, then under the earlier model/ directory. Nested paths must end in ‘.py’. Omit for run.py.”)]`NoNone
branch`Annotated[strNone, Field(description=‘Branch to execute; defaults to the model default.’)]`NoNone
commit_sha`Annotated[strNone, Field(description=‘Exact commit SHA for async runs; omit to use the branch tip.’)]`NoNone
parameters`Annotated[dict[str, Any]None, Field(description=‘Optional JSON object written to /inputs/parameters.json.’)]`NoNone
sensitivity`Annotated[SensitivityPlanSpecNone, Field(description=‘Optional bounded local sensitivity plan. Requires the full baseline parameters object and a plan containing baseline_commit_sha, parameter_variations, and numeric metric selectors. execute=false (default) returns a run-count/resource plan; reuse its experiment_id with execute=true to start or safely retry the serial batch.’)]`NoNone
parameter_matrix`Annotated[ParameterMatrixPlanSpecNone, Field(description=“Optional bounded set of exact parameter scenarios. Requires mode=‘sync’, scope=‘model’, full per-row parameters, and a 40-character immutable baseline_commit_sha. execute=false (default) returns stable child run IDs and cost limits; reuse group_id with execute=true to start or replay the group. An optional table_union/v1 reducer reads exact successful child artifacts and publishes a separately traceable master output.”)]`NoNone
cpu_profile`Annotated[Literal[2, 4, 8]None, Field(description=‘Optional quota-backed 2, 4, or 8 vCPU sandbox profile. Requires an active Pro, Team, or Enterprise plan and deployment admission capacity. The default backend profile is used when omitted.’)]`NoNone
outputs_previewAnnotated[bool, Field(description='Include bounded output previews for sync runs. Defaults to false so the response carries an artifact index; set true only when inline detail is needed.')]NoFalse
strict_sheet_inputsAnnotated[bool, Field(description='Reject dirty or error Native Sheet inputs even when every formula has a cached value. Formula cells without cached values are always rejected.')]NoFalse
strict_lineageAnnotated[bool, Field(description=OUTPUT_LINEAGE_AUTHORING_METADATA.minimum_strict_lineage_description)]NoFalse
timeout_seconds`Annotated[intNone, Field(description=‘Async model execution time limit in seconds. Omit to keep the 300-second default; async runs may opt into 900 or 1800 seconds. This bounds model execution only; queue, setup, upload, and cleanup use separate budgets.’)]`NoNone
checkpoint_generation_id`Annotated[strNone, Field(description=‘Optional exact checkpoint generation to seed this run from. Obtain a retained generation id from GET /api/models/{model_name}/checkpoints for the same branch.’)]`NoNone
publish_checkpointAnnotated[bool, Field(description='Publish a bounded checkpoint snapshot after a successful run. A cold publish requires an empty workspace; to advance a workspace, pass its current checkpoint_generation_id.')]NoFalse
ctx`ContextNone`NoNone
workspace_id`Annotated[strNone, Field(description=WORKSPACE_ID_FIELD_DESCRIPTION)]`NoNone

Returns a structured object. Top-level fields:

  • run_id (string)
  • model_name (string)
  • status (string)
  • commit_sha (string)
  • exit_code (integer)
  • outputs (object)

See the response example below for the full payload shape.

{
"name": "run_model",
"arguments": {
"mode": "sync",
"model_name": "forecasts",
"branch": "scenario/aggressive-growth",
"outputs_preview": true
}
}
{
"run_id": "66666666-6666-6666-6666-666666666666",
"model_name": "forecasts",
"status": "success",
"commit_sha": "abc1234def5678901234567890abcdef12345678",
"exit_code": 0,
"outputs": {
"revenue": [
100,
110,
121
]
}
}
  • Module: Execution
  • Requires an authenticated Bridge Town session (OAuth) or an API token.