--- title: "List pull requests that satisfy the query." method: POST path: "/filter/pull_requests" tags: ["filter", "default"] --- # List pull requests that satisfy the query. `POST /filter/pull_requests` ## Request - Base URL: `{{ server_url }}/v1` - URL: `{{ server_url }}/v1/filter/pull_requests` - Auth: one of: - HTTP bearer - API key in header `X-API-Key` - TypeScript: (a function with typed inputs; its response is checked against the schema) ## Request body - FilterPullRequestsRequest: Filters for `/filter/pull_requests`. Empty `properties` passes through all PRs matched by the other filters. - `account` integer, required: Session account ID. - `date_from` string, date, required: PRs must be updated later than or equal to this date. - `date_to` string, date, required: PRs must be updated earlier than or equal to this date. - `timezone` integer: Local time zone offset in minutes, used to adjust `date_from` and `date_to`. - `in` RepositoryID[], required: Set of repositories. An empty list raises a bad response 400. Duplicates are automatically ignored. - `events` PullRequestEvent[]: Allowed PR events that happened between `date_from` and `date_to`. - `stages` PullRequestStage[]: Allowed PR stages that are defined at `date_to`. - `with` PullRequestWith: Triage PRs by various developer participation. The aggregation is `OR` between the participation groups and `OR` within each group. For example, if our request is ``` {"author": ["github.com/vmarkovtsev"], "reviewer": ["github.com/gkwillie", "github.com/mcuadros"]} ``` then the matched PRs will have **@vmarkovtsev** as the author or either **@gkwillie** or **@mcuadros** as the reviewers. It is possible to mention whole teams using the syntax `{id}` where `id` is a team identifier (see `/teams`). - `author` DeveloperID[]: A set of developers. An empty list disables the filter and includes everybody. Duplicates are automatically ignored. - `reviewer` DeveloperID[]: A set of developers. An empty list disables the filter and includes everybody. Duplicates are automatically ignored. - `commit_author` DeveloperID[]: A set of developers. An empty list disables the filter and includes everybody. Duplicates are automatically ignored. - `commit_committer` DeveloperID[]: A set of developers. An empty list disables the filter and includes everybody. Duplicates are automatically ignored. - `commenter` DeveloperID[]: A set of developers. An empty list disables the filter and includes everybody. Duplicates are automatically ignored. - `merger` DeveloperID[]: A set of developers. An empty list disables the filter and includes everybody. Duplicates are automatically ignored. - `releaser` DeveloperID[]: A set of developers. An empty list disables the filter and includes everybody. Duplicates are automatically ignored. - `labels_include` string[]: At least one of these labels must be present in each returned PR. - `labels_exclude` string[]: None of these labels must be present in each returned PR. - `exclude_inactive` boolean, required: Value indicating whether PRs without events in the given time frame shall be ignored. - `jira` JIRAFilter: Filters related to JIRA traits. The aggregation between each filter type is *AND*. - `epics` string[]: JIRA issues must be included in the epics from the list. - `labels_include` string[]: Only issues having at least one label from the list will be included Several labels may be concatenated by a comma `,` so that all of them are required. - `labels_exclude` string[]: Issues having one label from the list will be excluded. - `issue_types` string[]: Issues must have one of the given types, e.g. Bug, Task, Design Document, etc. - `priorities` string[]: Issues must have a priority from the given list. - `projects` string[]: Issues must be contained in a project in the given project keys list. - `status_categories` JIRAStatusCategory[]: The JIRA issues must have a status belonging to one of these categories. - `unmapped` boolean: Select PRs that are not mapped to any JIRA issue. May not be specified with anything else. - `updated_from` string, date: Paginate the response: the returned PRs are updated on GitHub no older than this timestamp, including the beginning. Note: "updated on GitHub" means that we don´t consider release or deployment timestamps. Use this field only to paginate after calling `/paginate/pull_requests`. Subject of future changes. - `updated_to` string, date: Paginate the response: the returned PRs are updated on GitHub no later than this timestamp, not including the ending. Note: "updated on GitHub" means that we don´t consider release or deployment timestamps. Use this field only to paginate after calling `/paginate/pull_requests`. Subject of future changes. - `limit` integer, nullable: Maximum number of pull requests to return. The list is sorted by the last update timestamp. `null` means no limit. - `environments` string[]: Target environments for the deployment events, impacts `events` and `stages`. If omitted, we match any deployment in any environment. ## Response `200` List of pull requests satisfying the specified filters. - PullRequestSet: List of pull requests together with the participant profile pictures. - `include` object, required: Mentioned deployments. - `users` object, required: Mapping user native (e.g., GitHub) login ID -> user details. The users are mentioned in the PRs from "PullRequestSet.data" or in the commits from "FilterCommitsRequest.data". - `deployments` object: Mapping deployment names to their details. - `data` PullRequest[], required: List of matched pull requests. - `repository` string, required: PR is/was open in this repository. - `number` integer, required: PR number. - `title` string, required: Title of the PR. - `size_added` integer, required: Overall number of lines added. - `size_removed` integer, required: Overall number of lines removed. - `files_changed` integer, required: Number of files changed in this PR. - `created` string, date-time, required: When this PR was created. - `updated` string, date-time, required: When this PR was last updated. - `closed` string, date-time: When this PR was last closed. - `comments` integer, required: Number of *regular* (not review) comments in this PR. - `commits` integer, required: Number of commits in this PR. - `review_requested` string, date-time: When was the first time the author of this PR requested a review. - `first_review` string, date-time: When the first review of this PR happened. - `approved` string, date-time: When this PR was approved. - `review_comments` integer: Number of review comments this PR received. A review comment is left at a specific line in a specific file. In other words: review summaries are *not* considered review comments; refer to `reviews`. Comments by the PR author are considered as `comments`, not as `review_comments`. - `reviews` integer: Number of times this PR was reviewed. Reviews by the PR author are not taken into account. - `merged` string, date-time: When this PR was merged. - `merged_with_failed_check_runs` string[]: PR was merged with these failed check runs. - `released` string, date-time: When this PR was released. - `release_url` string, url: URL of the earliest release that includes this merged PR. - `deployments` string[]: List of deployments that contain this PR. - `stage_timings` StageTimings, required: Time spent by the PR in each pipeline stage. The deployments are independent of the releases. If the release happens before the deployment, the deployment time measures from the release event. If the release happens after the deployment, the two values are independent and both measure from the PR merge event. - `wip` string, required: Time duration value. - `review` string: Time duration value. - `merge` string: Time duration value. - `release` string: Time duration value. - `deploy` object: Map from target environments to the values. - `events_time_machine` PullRequestEvent[]: List of PR events which happened until `date_to`. `date_from` does not matter. - `stages_time_machine` PullRequestStage[]: List of PR stages as of `date_to` (normally, of length 1). - `events_now` PullRequestEvent[], required: List of PR events that ever happened. - `stages_now` PullRequestStage[], required: List of current PR stages (normally, of length 1). - `participants` PullRequestParticipant[], required: List of developers related to this PR. - `id` string, required: Person identifier. - `status` string[], required - `labels` PullRequestLabel[]: List of PR labels. - `name` string, required - `description` string - `color` string, required: RGB 24-bit color in hex. - `jira` LinkedJIRAIssue[]: List of linked JIRA issues. - `id` string, required: JIRA issue key `PROJECT-###`. - `title` string, required: Title of this issue. - `epic` string: Identifier of the epic that owns this issue. - `labels` string[]: List of JIRA labels in this issue. - `type` string, required: Type of this issue. ## Other responses - `400`: The request is invalid. - `403`: Calling user is not allowed to access the specified repositories. - `404`: The specified account does not exist or the user is not a member. - `422`: The account's installation has not finished yet. - `424`: One or more logical repositories miss the release settings. ## Changes - **2023-03-03** `f9fdd9fbfc25`: 1 info - added the new optional request property `jira/status_categories` - **2023-01-13** `d08637dcd231`: 2 breaking, 1 info - the `include/allOf[#/components/schemas/IncludedDeployments]/deployments/additionalProperties/name` response property's maxLength was unset from `100` for the response status `200` - the `include/allOf[#/components/schemas/IncludedDeployments]/deployments/additionalProperties/name` response property's minLength was decreased from `1` to `0` for the response status `200` - the `include/allOf[#/components/schemas/IncludedDeployments]/deployments/additionalProperties/name` response's property pattern `^([^'\s]| ){1,100}$` was added for the status `200` [Operation history](https://skmtc.dev/athenian/apis/title/changes/filter/pull_requests/post.md) --- [API](https://skmtc.dev/athenian/apis/title.md) - [All operations](https://skmtc.dev/athenian/apis/title/llms.txt) - [OpenAPI document](https://skmtc.dev/athenian/apis/title/revisions/110c9f7cffdd?raw)