list_pull_requests

List pull requests (merge requests) in a model. Requires at least Viewer role. state filter: ‘open’ (default), ‘closed’, or ‘all’. Set review_requested=‘me’ with state=‘open’ to return only your outstanding explicit review assignments; the filter uses your authenticated workspace user. Results are capped at limit (default 25, max 50).

read-only · idempotent

Parameters

Name	Type	Required	Default	Description
`model_name`	`Annotated[str, Field(description='Name of the Bridge Town model.')]`	Yes	—
`state`	`Annotated[Literal['open', 'closed', 'all'], Field(description="Filter by state: 'open' (default), 'closed', or 'all'.")]`	No	`'open'`
`limit`	`Annotated[int, Field(description='Maximum number of PRs to return. Defaults to 25, clamped to [1, 50]. When the model has more PRs than limit, truncated=true is set.')]`	No	`25`
`cursor`	`Annotated[str	None, Field(description=‘Opaque continuation cursor from a previous list_pull_requests response.’)]`	No	`None`
`review_requested`	`Annotated[Literal[‘me’]	None, Field(description=“Set to ‘me’ to return only open pull requests with an outstanding explicit review assignment for your authenticated workspace user.”)]`	No	`None`
`workspace_id`	`Annotated[str	None, Field(description=WORKSPACE_ID_FIELD_DESCRIPTION)]`	No	`None`

Returns

Returns a structured object. Top-level fields:

model (string)
state_filter (string)
pull_requests (array<object>)
count (integer)
total_count (integer)
truncated (boolean)
has_more (boolean)
next_cursor (null)
review_requested (string)
workspace_id (string)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "list_pull_requests",
  "arguments": {
    "model_name": "forecasts",
    "state": "open",
    "review_requested": "me"
  }
}

Response

{
  "model": "forecasts",
  "state_filter": "open",
  "pull_requests": [
    {
      "pull_request_id": 42,
      "title": "Aggressive growth scenario",
      "head_branch": "scenario/aggressive-growth",
      "base_branch": "main",
      "state": "open",
      "author": {
        "kind": "human",
        "display_name": "Alice"
      },
      "created_at": "2026-04-28T10:00:00+00:00",
      "updated_at": "2026-04-28T10:00:00+00:00",
      "merged": false,
      "lifecycle": "open",
      "head_sha": "def456abc123",
      "changed_file_count": 3,
      "input_sheets_changed": false,
      "requested_reviewers": [
        {
          "reviewer_user_id": "22222222-2222-2222-2222-222222222222",
          "display_name": "Bob",
          "state": "requested",
          "review_submitted_at": null
        }
      ],
      "reviewer_assignment_version": 1,
      "viewer_has_outstanding_request": true,
      "viewer_approval_required": false,
      "approval_status": {
        "approval_count": 0,
        "required_approvals": 1,
        "independent_approval_required": false,
        "independent_approval_source": "platform_default",
        "independent_approval_version": 0,
        "independence_satisfied": true,
        "viewer_is_author": false,
        "viewer_can_approve": true,
        "viewer_has_outstanding_request": true,
        "viewer_approval_required": false,
        "ready_to_merge": false,
        "blocking_reason": "denied by merge-policy:platform_default:v1: requires 1 eligible distinct approval(s) from actor kinds [human, delegated_agent, api_token], but found 0",
        "approval_rule": "merge-policy:platform_default:v1",
        "independence_rule": "independent-approval:platform_default:v0:optional"
      },
      "approval_summary_available": true,
      "actor": {
        "kind": "human",
        "display_name": "Bob"
      }
    }
  ],
  "count": 1,
  "total_count": 1,
  "truncated": false,
  "has_more": false,
  "next_cursor": null,
  "review_requested": "me",
  "workspace_id": "dddddddd-dddd-dddd-dddd-dddddddddddd"
}

Notes

Module: Pull Requests
Requires an authenticated Bridge Town session (OAuth) or an API token.
review_requested='me' uses the authenticated workspace user and includes only open PRs with that user’s outstanding explicit assignment.
A review request is distinct from approval eligibility and does not make that reviewer individually required by merge policy.
Listing is read-only: it sends no review email and does not execute the model.
Reviewer states include requested, approved, changes_requested, commented, stale, dismissed, removed, and unavailable; removed reviewers’ identities are redacted.
When approval_summary_available is false, approval_status is null rather than a fabricated zero-count decision.