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.
Parameters
Section titled “Parameters”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
mode | Annotated[Literal['sync', 'async'], Field(description='Run synchronously or queue asynchronously.')] | Yes | — | |
model_name | Annotated[str, Field(description='Name of the Bridge Town model to execute.')] | Yes | — | |
path | `Annotated[str | None, 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.”)]` | No | None |
branch | `Annotated[str | None, Field(description=‘Branch to execute; defaults to the model default.’)]` | No | None |
commit_sha | `Annotated[str | None, Field(description=‘Exact commit SHA for async runs; omit to use the branch tip.’)]` | No | None |
parameters | `Annotated[dict[str, Any] | None, Field(description=‘Optional JSON object written to /inputs/parameters.json.’)]` | No | None |
sensitivity | `Annotated[SensitivityPlanSpec | None, 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.’)]` | No | None |
parameter_matrix | `Annotated[ParameterMatrixPlanSpec | None, 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.”)]` | No | None |
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.’)]` | No | None |
outputs_preview | Annotated[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.')] | No | False | |
strict_sheet_inputs | Annotated[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.')] | No | False | |
strict_lineage | Annotated[bool, Field(description=OUTPUT_LINEAGE_AUTHORING_METADATA.minimum_strict_lineage_description)] | No | False | |
timeout_seconds | `Annotated[int | None, 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.’)]` | No | None |
checkpoint_generation_id | `Annotated[str | None, 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.’)]` | No | None |
publish_checkpoint | Annotated[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.')] | No | False | |
ctx | `Context | None` | No | None |
workspace_id | `Annotated[str | None, Field(description=WORKSPACE_ID_FIELD_DESCRIPTION)]` | No | None |
Returns
Section titled “Returns”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.
Example
Section titled “Example”Tool Call
Section titled “Tool Call”{ "name": "run_model", "arguments": { "mode": "sync", "model_name": "forecasts", "branch": "scenario/aggressive-growth", "outputs_preview": true }}Response
Section titled “Response”{ "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.