> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coderabbit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Read pull requests

> Read current pull-request metadata, review observations, checks, and paginated review threads.

GitHub Cloud (Available for GitHub Cloud.)

Pull-request reads support GitHub Cloud organizations with the caller's existing repository access. Self-hosted instances are not supported. Use your organization's [regional REST base URL](https://docs.coderabbit.ai/api/platform-api.md#availability); examples use the US URL. Hosted MCP is available only for US organizations.

Use pull-request reads to inspect a repository you can currently access. First find its Git provider ID with [repository reads](https://docs.coderabbit.ai/api/platform-repositories.md). These operations use the same API-key authentication and organization selection as [the Platform API](https://docs.coderabbit.ai/api/platform-api.md).

## List pull requests

```bash theme={null}
printf 'x-coderabbitai-api-key: %s\n' "$CODERABBIT_API_KEY" | \
  curl --fail-with-body --header @- --get \
  'https://api.coderabbit.ai/v1/repositories/12345678/pull-requests' \
  --data-urlencode 'author=all' \
  --data-urlencode 'state=open' \
  --data-urlencode 'page_size=50'
```

The default `author=me` listing contains open pull requests authored by the API key owner's linked GitHub account. Use `author=all` to include other authors, or provide a GitHub login. `head_branch` and `head_owner` narrow the source branch and repository owner, including forks. The [endpoint reference](https://docs.coderabbit.ai/api-reference/platform-pull-requests-list) describes every filter and response field.

Results use `data` and `next_page_token`. Pass a returned token as `page_token` with the same repository, credential, organization, filters, and page size. Continue even when `data` is empty; stop when the token is `null`. Tokens expire after 10 minutes. Expired or incompatible tokens return `400 invalid_request`.

Listings use live GitHub search and can change between pages. They do not provide a historical snapshot or an exhaustive export when GitHub's search limit is reached. Check `coverage.limitations` and narrow the filters when necessary.

## Read one pull request

The repository ID and pull-request number identify different resources. Use the repository's provider ID in the first path segment and its local pull-request number in the final segment. An opaque PR `id` from a response cannot replace the number.

```bash theme={null}
printf 'x-coderabbitai-api-key: %s\n' "$CODERABBIT_API_KEY" | \
  curl --fail-with-body --header @- --get \
  'https://api.coderabbit.ai/v1/repositories/12345678/pull-requests/42' \
  --data-urlencode 'include=checks' \
  --data-urlencode 'include=threads' \
  --data-urlencode 'thread_page_size=50'
```

The response separates PR metadata, review observations, merge state, checks, and threads. Detailed checks are included by default. Request threads explicitly with `include=threads`; repeated `include` parameters select both sections. Use `include=none` for core metadata without checks or threads. `none` cannot be combined with another section. See the [endpoint reference](https://docs.coderabbit.ai/api-reference/platform-pull-requests-get) for the generated schema.

## Use the CLI

Use CodeRabbit CLI **0.9.4 or later**. After signing in with an agentic organization key, the CLI returns the same JSON as the API:

```bash theme={null}
coderabbit api pull-requests list 12345678 \
  --author all --page-size 50

coderabbit api pull-requests get 12345678 42 \
  --include checks,threads --thread-page-size 50
```

Use `--include none` for core metadata only. Continue a listing with `--page-token`, or continue review threads with `--thread-page-token`. Keep the same repository, organization, and filters when using either token.

## Read CodeRabbit review state

Use `GET /v1/repositories/{repository_id}/pull-requests/{pull_request_number}/review` to read the existing CodeRabbit review observation shown by Triage. It uses the same authentication, repository access checks, and read quota as the other pull-request reads.

```bash theme={null}
coderabbit api pull-requests review-status \
  12345678 42
```

In hosted MCP, call `get_pull_request_review` with `repository_id` and `pull_request_number`. The connection must include `account:read` and `pull_requests:read` consent.

The response keeps the provider's current `head_sha` separate from the observation's `target_commit_sha`. A missing or different target is not evidence that the current head was reviewed. Even a `completed` observation does not prove that review results were published.

`unconfirmed` means progress has not been confirmed recently. It does not establish that execution stopped, and it preserves the original observation timestamp and target. `review: null` means no usable observation is available; it does not prove that no review ran. The indexed observation can lag the provider's current head.

See the [review-state reference](https://docs.coderabbit.ai/api-reference/platform-pull-request-review-get) for the generated response fields and statuses. This read does not start a review.

## Interpret observations

| Field | What it establishes |
| - | - |
| `pull_request.head_sha` | The head commit observed for the PR. |
| `head_changed` | Whether the observed head differs from `expected_head_sha`, when supplied. |
| `reviews.coderabbit` | Available CodeRabbit review evidence from the provider, including unknown or incomplete states. |
| `checks.requiredness_known` | Whether required-check status is known. A passing check alone does not establish that branch rules are satisfied. |
| `coverage.limitations` | Missing or incomplete observations that affect interpretation. |

These fields do not establish that CodeRabbit finished reviewing the current head. A bot comment, an unknown review state, or passing checks alone does not prove completion. Merge eligibility can also depend on branch rules and the acting user's permissions.

## Continue review threads

Threads have their own page token under `threads.next_page_token`. Reuse it as `thread_page_token` while preserving `include=threads` and the thread filters. Thread roots default to unresolved CodeRabbit threads. `thread_author=all` includes other authors, while reply context retains its original authors.

```bash theme={null}
printf 'x-coderabbitai-api-key: %s\n' "$CODERABBIT_API_KEY" | \
  curl --fail-with-body --header @- --get \
  'https://api.coderabbit.ai/v1/repositories/12345678/pull-requests/42' \
  --data-urlencode 'include=threads' \
  --data-urlencode 'thread_page_size=50' \
  --data-urlencode "thread_page_token=$THREAD_PAGE_TOKEN"
```

Check `replies_complete` and `reply_count` on each thread. Reply context can be incomplete; follow the thread's source link for the full discussion. Thread and review data can change without a new commit.

On a fresh read, `expected_head_sha` is a comparison value: a different current head returns `200` with `head_changed: true` and the current `head_sha`. This does not wait for a review or mean that a review completed.

If the head changes during a read or between thread pages, the API returns `409 head_changed`. Restart without the page token.

## Access and recovery

Every request checks current access. A PR outside the selected installation, an inaccessible repository, or a repository that has been deleted and recreated under the same name returns `404 not_found`. The endpoint does not grant access based on a repository name or a previously issued cursor.

For `503 unavailable`, retry after the dependency recovers. For `429 rate_limit_exceeded`, respect `Retry-After` and `error.retry_after` when present. Avoid frequent polling; these reads share the public API request budget.

## What's next

> [card] [List pull requests](https://docs.coderabbit.ai/api-reference/platform-pull-requests-list)
>
> Explore the filters and paginated response schema.

> [card] [Read a pull request](https://docs.coderabbit.ai/api-reference/platform-pull-requests-get)
>
> Inspect review, merge, check, and thread fields.

> [card] [Read CodeRabbit review state](https://docs.coderabbit.ai/api-reference/platform-pull-request-review-get)
>
> Inspect the existing review observation and its target commit.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.