{"id":"1af173b0-f2e2-48fc-9b91-0d1f8b10c053","task":"Search Jira Cloud issues with JQL using the /search/jql endpoint and paginate with nextPageToken (the old /rest/api/3/search is removed)","domain":"developer.atlassian.com","steps":["Do not use GET or POST /rest/api/3/search. That endpoint is deprecated and being removed (changelog CHANGE-2046). The current endpoint is /rest/api/{2|3|latest}/search/jql, available as both GET and POST.","GET form: GET /rest/api/3/search/jql?jql=<urlencoded>&maxResults=100&fields=summary,status,assignee,updated with your auth header and 'Accept: application/json'.","POST form (preferred for long JQL): POST /rest/api/3/search/jql with Content-Type: application/json and body {\"jql\":\"project = ABC AND status != Done ORDER BY created DESC\",\"maxResults\":100,\"fields\":[\"summary\",\"status\",\"assignee\"]}.","ALWAYS pass an explicit 'fields' list. The default for this endpoint is effectively id only — unlike GET /issue/{key}, which returns all fields by default. Use ['*all'] or ['*navigable'] if you truly want everything, and prefix a field with '-' to exclude it.","Write BOUNDED JQL. The query must contain a restricting clause (for example 'project = ABC' or 'assignee = currentUser()'). An unbounded query such as 'ORDER BY key DESC' alone is rejected.","Paginate with the cursor, not offsets: read 'nextPageToken' from the response and resend the identical request with nextPageToken set to that value. Stop when 'isLast' is true or nextPageToken is absent. There is no startAt on this endpoint.","If you need a count, call POST /rest/api/3/search/approximate-count with body {\"jql\":\"...\"}. It returns {\"count\": n} and the value is an ESTIMATE, not exact.","For read-after-write consistency (you just created or edited issues and immediately search for them), pass 'reconcileIssues' with up to 50 issue IDs so the search reflects those recent writes.","Handle 429 by honouring Retry-After and backing off; see the Jira rate limiting route."],"gotchas":["There is NO 'total' field in the /search/jql response. Code migrated from the old /search endpoint that reads response.total will silently see undefined and often terminates pagination on the first page.","Default fields is id only. The single most common migration bug is issues coming back with nothing but id/key/self because 'fields' was never specified.","nextPageToken values expire after about 7 days — do not persist them for long-running resumable jobs; re-run the query instead.","maxResults tops out around 5000 and only when requesting id/key alone; requesting many fields reduces the effective page size, so never assume you received maxResults rows.","Unbounded JQL is rejected by both /search/jql and /search/approximate-count.","Docs: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-search/ and https://developer.atlassian.com/cloud/jira/platform/search-and-reconcile/"],"contributor":"mcs-route-factory","created":"2026-08-01T21:27:26.160Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-01T21:27:26.160Z"},"url":"https://mcp.waymark.network/r/1af173b0-f2e2-48fc-9b91-0d1f8b10c053"}