list_commentary

Discover run commentary across runs and models accessible to the caller, or fetch a single commentary row by id. Pass commentary_id to fetch exactly one row (ignoring model_name/run_id/output_name/include_archived); pass include_versions=true alongside it to also receive the row’s full append-only version history, ordered oldest-first — the trail is exactly the rows persisted by prior upsert_commentary calls.

read-only · idempotent

Parameters

Name	Type	Required	Default	Description
commentary_id	Annotated[str, Field(description='UUID of a single commentary row to fetch. When set, every other filter (model_name/run_id/output_name/include_archived) is ignored.')]	No	''
include_versions	Annotated[bool, Field(description='When true (requires commentary_id), include the full version history of that single commentary row.')]	No	False
model_name	Annotated[str, Field(description='Name of the Bridge Town model to list commentary for.')]	No	''
run_id	Annotated[str, Field(description='UUID of the model run to attach commentary to.')]	No	''
output_name	Annotated[str, Field(description='Named output within the run that this commentary describes.')]	No	''
include_archived	Annotated[bool, Field(description='When true, include archived commentary in the results.')]	No	False
limit	Annotated[int, Field(ge=1, le=200, description='Maximum commentary rows per page (default 50).')]	No	50
cursor	`Annotated[str	None, Field(description=‘Opaque continuation cursor from a previous list_commentary response.’)]`	No	None
workspace_id	`Annotated[str	None, Field(description=ID_BACKED_WORKSPACE_ID_FIELD_DESCRIPTION + ’ Only takes effect when commentary_id or run_id is also passed — the model_name-only and cross-model listing modes stay scoped to your current workspace.’)]`	No	None

Returns

Returns a structured object. Top-level fields:

• commentary (array<object>)
• total_returned (integer)
• total_count (integer)
• truncated (boolean)
• versions (array<object>)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "list_commentary",
  "arguments": {
    "commentary_id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "include_versions": true
  }
}

Response

{
  "commentary": [
    {
      "commentary_id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "workspace_id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
      "model_name": "forecasts",
      "run_id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "output_name": "revenue",
      "author": {
        "kind": "human",
        "display_name": "Analyst"
      },
      "text": "Revenue beat plan by 12% in March, mostly from SaaS expansion.",
      "version": 1,
      "archived_at": null,
      "archived_by": null,
      "created_at": "2026-04-28T10:00:00+00:00",
      "updated_at": "2026-04-28T10:00:00+00:00"
    }
  ],
  "total_returned": 1,
  "total_count": 1,
  "truncated": false,
  "versions": [
    {
      "version_id": "11111111-1111-1111-1111-111111111111",
      "commentary_id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "workspace_id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
      "version": 1,
      "text": "Revenue beat plan by 12% in March, mostly from SaaS expansion.",
      "author": {
        "kind": "human",
        "display_name": "Analyst"
      },
      "change_note": "Initial variance readout",
      "created_at": "2026-04-28T10:00:00+00:00"
    }
  ]
}

Notes

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