run_model

Use run_model for the normal run.py model entry point, or pass path to run one explicitly named file instead. Choose sync or async based on expected duration; follow async runs with get_run or list_runs. Provides view: run-output (ui://apps/run-output) renders this tool’s result when MCP Apps are available.

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=‘Model-relative Python file or script name to execute, instead of the normal run.py entry point. Advanced path; omit for normal whole-model execution.’)]`	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
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='Require an emitted, valid, persisted, and indexed output-lineage trace. Outputs remain retrievable if this policy fails after execution.')]	No	False
ctx	`Context	None`	No	None
workspace_id	`Annotated[str	None, Field(description=WORKSPACE_ID_FIELD_DESCRIPTION)]`	No	None

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

Tool Call

{
  "name": "run_model",
  "arguments": {
    "mode": "sync",
    "model_name": "forecasts",
    "branch": "scenario/aggressive-growth",
    "outputs_preview": true
  }
}

Response

{
  "run_id": "66666666-6666-6666-6666-666666666666",
  "model_name": "forecasts",
  "status": "success",
  "commit_sha": "abc1234def5678901234567890abcdef12345678",
  "exit_code": 0,
  "outputs": {
    "revenue": [
      100,
      110,
      121
    ]
  }
}

Notes

• Module: Execution
• Requires an authenticated Bridge Town session (OAuth) or an API token.