run

Use run to execute a model via run.py or one file/script inside it. Decide sync versus async from expected duration; follow async runs with get_run or list_runs.

Parameters

Name	Type	Required	Default	Description
scope	Annotated[Literal['model', 'file'], Field(description="Execution scope. 'model' runs run.py as the model's top-level entry point (omit path); 'file' runs a single file/script inside the model named path.")]	Yes	—
mode	Annotated[Literal['sync', 'async'], Field(description="Execution mode. 'sync' blocks until the run completes and returns results inline; 'async' queues the run immediately and returns a run_id to poll with get_run.")]	Yes	—
model_name	Annotated[str, Field(description='Name of the Bridge Town model to execute.')]	Yes	—
path	`Annotated[str	None, Field(description=“Name of the file/script to run (without .py extension). Required when scope=‘file’; ignored when scope=‘model’.”)]`	No	None
branch	`Annotated[str	None, Field(description=“Branch to execute from. Defaults to the model’s default branch when omitted or null.”)]`	No	None
commit_sha	`Annotated[str	None, Field(description=‘Exact git commit SHA to execute. When omitted, the latest commit on branch is used.’)]`	No	None
parameters	`Annotated[dict[str, Any]	None, Field(description=‘Optional JSON object delivered as /inputs/parameters.json inside the sandbox container. Use for sensitivity analysis without branching. Must be JSON-serializable and under 64 KB.’)]`	No	None
outputs_preview	Annotated[bool, Field(description="mode='sync' only. When true (default), the outputs field carries bounded inline content previews for each output artifact. Set false to return only output name/type/size metadata — use this when you only need run status and exit_code and will fetch specific output content afterward with get_run_output. Ignored for mode='async', which never returns outputs inline.")]	No	True
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)
• branch (null)
• commit_sha (string)
• status (string)
• exit_code (integer)
• stdout (string)
• stderr (string)
• stdout_truncated (boolean)
• stderr_truncated (boolean)
• outputs (object)
• duration_seconds (number)
• data_snapshot_ref (null)
• error (null)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "run",
  "arguments": {
    "scope": "model",
    "mode": "sync",
    "model_name": "forecasts"
  }
}

Response

{
  "run_id": "66666666-6666-6666-6666-666666666666",
  "model_name": "forecasts",
  "branch": null,
  "commit_sha": "abc1234def5678901234567890abcdef12345678",
  "status": "success",
  "exit_code": 0,
  "stdout": "Run completed in 1.42s\n",
  "stderr": "",
  "stdout_truncated": false,
  "stderr_truncated": false,
  "outputs": {
    "revenue": [
      100,
      110,
      121
    ]
  },
  "duration_seconds": 1.42,
  "data_snapshot_ref": null,
  "error": null
}

Notes

• Module: Execution
• Requires authentication via API token or Auth0 JWT.