diff --git a/docs/codacy-cloud-cli/index.md b/docs/codacy-cloud-cli/index.md
index af6ab1c482..8efaa80388 100644
--- a/docs/codacy-cloud-cli/index.md
+++ b/docs/codacy-cloud-cli/index.md
@@ -162,6 +162,21 @@ This information is also included when using `--output json`.
 !!! note
     Not every advisory lists specific affected functions — this section only appears when Codacy has identified them.
 
+### List and filter pull requests
+
+```bash
+# List open pull requests (default)
+codacy pull-requests gh my-org my-repo
+
+# Filter by title or author handle, and by base branch
+codacy pull-requests gh my-org my-repo --search "fix flaky" --base main
+
+# List closed pull requests instead
+codacy pull-requests gh my-org my-repo --state closed
+```
+
+`pull-requests` (alias `prs`) mirrors the [Pull Requests page filters](../repositories/pull-requests.md#filtering): `--search`/`-q` matches the title or author handle, and `--base`/`-B` matches the pull request's base branch.
+
 ### Inspect pull requests
 
 ```bash
diff --git a/docs/repositories/images/pull-request-filters.png b/docs/repositories/images/pull-request-filters.png
new file mode 100644
index 0000000000..332d9280d7
Binary files /dev/null and b/docs/repositories/images/pull-request-filters.png differ
diff --git a/docs/repositories/pull-requests.md b/docs/repositories/pull-requests.md
index e0aad11c72..2aa463a6ad 100644
--- a/docs/repositories/pull-requests.md
+++ b/docs/repositories/pull-requests.md
@@ -11,6 +11,22 @@ By default, the page lists open pull requests, but you can click the **Closed**
 
 ![Pull Requests page](images/pull-requests.png)
 
+## Filtering pull requests {: id="filtering"}
+
+Above the **Open** and **Closed** tabs, use the search box and the branch switch to narrow down the pull request list:
+
+-   **Search**: type at least 3 characters to filter pull requests by title or author handle. The search applies to both the Open and Closed tabs.
+-   **Branch switch**: click **View all target branches** to choose between:
+    -   **Targeting any branch** (the default): shows every pull request, regardless of its base branch.
+    -   **Targeting current branch**: shows only pull requests whose base branch matches the branch currently selected for the repository.
+
+The Open and Closed counts update to match the selected branch, but aren't affected by the search text.
+
+![Filtering pull requests](images/pull-request-filters.png)
+
+!!! tip
+    The [Codacy Cloud CLI](../codacy-cloud-cli/index.md) supports the same filters, for example `codacy pull-requests gh my-org my-repo --search "fix flaky" --base main`.
+
 Click a specific pull request to see detailed information about the code quality changes introduced by that pull request.
 
 !!! tip