refresh_output_sheet_view

Re-materialize an existing output sheet view from a newer successful run of the same model, replacing its tab content and provenance while keeping the same sheet_id and tab_id. Commits to the sheet’s existing Git path — prior versions remain readable from Git history, unlike deleting and recreating the sheet.

Parameters

Name	Type	Required	Default	Description
model_name	Annotated[str, Field(description='Name of the Bridge Town model that owns the sheet and the run.')]	Yes	—
sheet_id	Annotated[str, Field(description='sheet_id of the existing output sheet view to refresh, as returned by create_output_sheet_view, list_native_sheets, or get_native_sheet.')]	Yes	—
run_id	Annotated[str, Field(description='UUID (or unique prefix) of the newer completed model run to re-materialize the sheet view from.')]	Yes	—
output_name	`Annotated[str	None, Field(description=“Name of the run output to render as the refreshed sheet. Defaults to the sheet’s current output_name (from its provenance) when omitted. Resolves with or without a trailing ‘.json’ when unambiguous.”)]`	No	None
branch	`Annotated[str	None, Field(description=“Branch the sheet view lives on. Defaults to the model’s default/unresolved branch — never the most-recently-updated row across branches. Pass the exact branch to scope a scenario branch’s sheet; refreshing on one branch never affects another branch’s copy of the same sheet_id.”)]`	No	None
expected_sha	Annotated[str, Field(description="Expected blob SHA-1 (40 hex chars) of the sheet's current .btsheet.json, for optimistic concurrency control -- pass the sha returned by a prior create_output_sheet_view/refresh_output_sheet_view/get_native_sheet call. If the sheet was modified since, the call fails with a commit-conflict error. Omit to overwrite unconditionally.")]	No	''
commit_message	Annotated[str, Field(description='Git commit message. If omitted, the server generates a default message.')]	No	''

Returns

Returns a structured object. Top-level fields:

• model_name (string)
• sheet_id (string)
• name (string)
• purpose (string)
• run_id (string)
• run_branch (string)
• run_commit_sha (string)
• previous_run_id (string)
• output_name (string)
• branch (string)
• commit_sha (string)
• sha (string)
• tab_id (string)
• tab_count (integer)
• row_count (integer)
• column_count (integer)
• data_hash (string)
• generated_at (string)
• calculation_status (string)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "refresh_output_sheet_view",
  "arguments": {
    "model_name": "forecasts",
    "sheet_id": "sht_7890a1b2c3d4e5f67890a1b2c3d4e5f6",
    "run_id": "77777777-7777-4777-8777-777777777777"
  }
}

Response

{
  "model_name": "forecasts",
  "sheet_id": "sht_7890a1b2c3d4e5f67890a1b2c3d4e5f6",
  "name": "revenue_by_quarter (run 66666666)",
  "purpose": "output",
  "run_id": "77777777-7777-4777-8777-777777777777",
  "run_branch": "main",
  "run_commit_sha": "abc1234def5678901234567890abcdef12345678",
  "previous_run_id": "66666666-6666-6666-6666-666666666666",
  "output_name": "revenue_by_quarter",
  "branch": "main",
  "commit_sha": "abc1234def5678901234567890abcdef12345678",
  "sha": "abc1234def5678901234567890abcdef12345678",
  "tab_id": "tab_890a1b2c3d4e5f67890a1b2c3d4e5f67",
  "tab_count": 1,
  "row_count": 6,
  "column_count": 3,
  "data_hash": "a1b2c3d4e5f678901a2b3c4d5e6f789012b3c4d5e6f7890a1b2c3d4e5f67890",
  "generated_at": "2026-04-28T10:00:00+00:00",
  "calculation_status": "clean"
}

Notes

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