list_commentary

Discover run commentary across runs and models accessible to the caller. All filters are AND-composed. When model_name and run_id are both omitted, the result is constrained to the caller’s accessible models so commentary from foreign models is never leaked. Pass include_archived=true to surface soft-deleted rows for audit/recovery flows.

read-only · idempotent

Parameters

Name	Type	Required	Default	Description
`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`
`workspace_id`	`Annotated[str	None, Field(description=ID_BACKED_WORKSPACE_ID_FIELD_DESCRIPTION + ’ Only takes effect when 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)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "list_commentary",
  "arguments": {
    "model_name": "forecasts",
    "run_id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
    "output_name": "revenue"
  }
}

Response

{
  "commentary": [
    {
      "commentary_id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "tenant_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "model_name": "forecasts",
      "run_id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "output_name": "revenue",
      "author_id": "22222222-2222-2222-2222-222222222222",
      "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
}

Notes

Module: Run Commentary
Requires authentication via API token or Auth0 JWT.