Handling JQL REST API searching exceeding max_result_window in Jira
Platform Notice: Data Center Only - This article only applies to Atlassian apps on the Data Center platform.
Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
This article explains how to handle JQL REST API searches that exceed the max_result_window in Jira.
Understanding the problem
When using the Jira REST API to search issues with JQL, you may hit a 500 error if you try to access results beyond the configured max_result_window (default: 10,000). This limit is set by the underlying search engine (OpenSearch or Lucene) and restricts how many results you can paginate through.
Example scenario:
You query
/rest/api/latest/search?maxResults=0&jql=project=MYPROJECTand see 15,000 issues.You paginate in batches of 100 using
startAtandmaxResults.When you reach
startAt=10000, the API returns an error or empty results due to themax_result_windowlimit:
<message>Search limit exceeded. We couldn't complete your search because it requests 10,100 results which exceeded the search platform limit of 10,000. Try refining your query or contact your Jira administrator. Repeating the same search may not work.</message>
<stack-trace>Please contact your admin passing attached Log's referral number: 91a9a4e4-244c-4d3a-939d-c50b92d49d02</stack-trace>What is the max result window
The max result window is the maximum number of results retrieved from the underlying search engine. While OpenSearch defaults to 10,000, Jira sets this value to int.max, but only requests up to the value configured in the jira.search.platform.max.result.window property (default: 10,000).
In the following sections, references to the max result window refer to the limit set by the jira.search.platform.max.result.window property. More about recognized application properties.
Why not increase the limit
Increasing the max result window isn’t recommended for most customers. It can significantly increase memory usage, slow search, and risk node instability or outages. If you notice performance issues, monitor your nodes and consider scaling resources.
Solution
Recommendations
Optimize your JQL query
Refine your JQL to reduce the result set below the max result window limit. For example, add date filters or additional criteria to narrow the search, such as: project=MYPROJECT AND updated >= -365d
Split queries by project
If you need to fetch issues across multiple projects, split your queries so each is project-scoped. You can get the projects by /project endpoint. More about endpoints.
Paginate with issue ID for a single project
This method only works for single-project queries. For multi-project or non-project-scoped queries, the results might be incomplete or inconsistent due to how Jira handles the id > {last_seen_id} filter.
For a single project, you can paginate beyond the max result window by using a deterministic order and filtering by issue ID. Start by fetching the first batch with the following request:
/rest/api/2/search?jql=project=MYPROJECT order by id ASC&startAt=0&maxResults=10000
After retrieving the results, note the last issue ID in the batch (for example, id=1595348). To fetch the next batch, use this ID in your next request:
/rest/api/2/search?jql=project=MYPROJECT AND id > 1595348 order by id ASC&startAt=0&maxResults=10000
Repeat this process as needed to retrieve additional issues.
(Advanced) Increase the max result window
Increasing the limit can impact system performance and stability.
Only consider increasing the max result window if it is absolutely necessary and you understand the risks involved. To raise the limit, change the Jira property jira.search.platform.max.result.window to a higher value.
Was this helpful?