GET /v1/origin/search/pulls
Searches pull requests with a pull request search query, in one namespace (an org or a user): across the repositories the query names with repo:, org: or user:, or across repo when it names none. Returns the same PullRequest items as ListPullRequests, most relevant first unless sort, or the query's sort:, orders them.
A query whose repo:, org: and user: name more than one namespace, or one that names none when repo is not set, is rejected with INVALID_ARGUMENT and a field violation on q; add org:NAME to search one namespace.
Search matches review state as well as pull request fields, so every caller needs both repository:pull_requests:read and repository:pull_requests:reviews:read, and search covers only repositories that grant the caller both. That check runs before the search, so neither results nor total_count reflect any other repository. A repository named with repo: that does not grant both is skipped. App installation tokens are rejected with PERMISSION_DENIED.
Searching with org: or user: needs a user credential that is not limited to specific repositories, or a service account: a managed account searches its owner's namespace, and a custom account the repositories in its owner's namespace that its API key is scoped to. A session token limited to specific repositories and a custom account whose key has no repository scope are rejected with PERMISSION_DENIED.
A mirrored repository whose pull requests live on its upstream source is searched only when repo: or repo names it, and only when that source is not a self-hosted enterprise server; mirrors of one are skipped. The caller needs the same access as for any other repository. Its pull requests come from the search index and carry fewer fields; see PullRequest. A search of such a repository accepts fewer qualifiers and sorts; see q.
A page holds at most page_size results and can hold fewer while next_page_token is set. Each request also counts against the caller's pull request search rate limit, which is separate from the public API quota: a user's searches share one budget across every credential, and each service account has its own, keyed by its sa_ id.
A query that does not parse, or asks for something search cannot answer, is rejected with INVALID_ARGUMENT naming its problems; see q. FAILED_PRECONDITION means one of four things, each named in the error message: search is not enabled for the caller; the caller can read too many repositories in the named org or user to search at once, so the query needs repo: in place of org: and user: (repo: alone for a service account whose API key names too many repositories); the caller belongs to too many teams to search review-requested:@me, team-review-requested-user:@me or review-involves:@me; or the search names more than 10 mirrored repositories whose pull requests live on their upstream source.
UNAVAILABLE means search cannot answer now, including when the upstream source of a named mirrored repository cannot say which of its repositories that mirror holds. Retry the request.
Request
- Base URLhttps://api.cursor.com
- AuthHTTP bearer
Query parameters
The search query: words to match plus qualifiers such as is:open, author:@me, label:bug and repo:owner/name, combined with AND, OR, NOT and parentheses. At most 1,024 UTF-16 code units. An empty query matches every pull request in the searched repositories.
A rejected query returns INVALID_ARGUMENT with one google.rpc.BadRequest field violation on q per problem. Every bad qualifier the parser rejects is named unless the query is too long or malformed: an over-long query is refused for its length alone, and a problem in how it is written, such as an unclosed quote, a standalone "", a doubled - or a parenthesis touching a word, is named without the qualifier problems. A misplaced operator or parenthesis, or the word or nesting limit, ends the check, and of the conflicts across the whole search, such as a second sort:, at most the first is named. A query that parses is then checked in stages, and only the first stage that finds a problem is named: a second namespace, then a person Origin does not know, then a qualifier that search cannot answer (is:queued, team:). When a problem has a location, its description ends with (at <start>-<end>): zero-based, end-exclusive UTF-16 code unit offsets into q.
repo: names a mirrored repository whose pull requests live on its upstream source by its name on this host; org: and user: never search one. While a search covers such a repository, it accepts only words, is:open, is:closed, is:merged, is:draft, draft:, is:pr, label:, has:label, no:label, head:, base:, created:, updated:, merged:, closed:, repo:, org:, user: and in:, and sorts only by created, updated or relevance. Any other qualifier or sort is rejected with INVALID_ARGUMENT.
Optional repository, as owner_slug/name, searched when q names no repo:, org: or user:. Ignored when it names one. Required when it names none: without it the request is rejected with INVALID_ARGUMENT. A repository that does not exist is rejected with NOT_FOUND, and one the caller cannot read pull requests or their reviews in with PERMISSION_DENIED. A mirrored repository whose pull requests live on its upstream source is searched through the search index, unless that source is a self-hosted enterprise server, in which case it contributes no results.
Maximum results to return. Defaults to 30; maximum 100.
Opaque cursor from a previous response's next_page_token. Empty for the first page. A token is valid only with the q, repo, sort and order that produced it. page_size on a follow-up request applies to that page; omit it to keep the previous page size.
Optional sort: created, updated, comments, reactions, reactions-<reaction>, interactions or relevance. When set it replaces any sort: in q. When empty, q's sort: applies, else most relevant first for a query with words and newest first for one without. A value that is not a sort is rejected with INVALID_ARGUMENT naming sort, and so is a sort search cannot answer.
Direction of sort: asc or desc, defaulting to desc. Ignored unless sort is set, so it never changes the direction of a sort: in q. Any other value is rejected with INVALID_ARGUMENT naming order.
Response
OK
Changes
No recorded changes to this operation across all 1 revision of this API.