--- title: "Compute the balanced pagination plan for `/filter/pull_requests`." method: POST path: "/paginate/pull_requests" tags: ["pagination", "default"] --- # Compute the balanced pagination plan for \`/filter/pull_requests\`. `POST /paginate/pull_requests` ## Request - Base URL: `{{ server_url }}/v1` - URL: `{{ server_url }}/v1/paginate/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 - PaginatePullRequestsRequest: Request of `/paginate/pull_requests`. According to the target batch size, compute the optimal PR updated timestamp ranges. `request` should match the body to be sent to `/filter/pull_requests`. `updated_from` and `updated_to` inside `request` are ignored. - `batch` integer, required: Target batch size. The returned ranges do not guarantee the exact match. - `request` FilterPullRequestsRequest, required: 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` Identifier of the created repository set. - PullRequestPaginationPlan: Response of `/paginate/pull_requests`. Computed split of the PR updated timestamp range. - `updated` string[]: Split borders in *descending* order. ## 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 `request/jira/status_categories` - **2022-11-16** `fcf829c0439e`: 1 info - added the new optional request property `request/jira/priorities` - **2022-11-16** `cb74c2b3ef0d`: 1 warning - removed the request property `request/jira/priorities` - **2022-11-16** `7ce5052fc811`: 1 info - added the new optional request property `request/jira/priorities` [Operation history](https://skmtc.dev/athenian/apis/title/changes/paginate/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)