EST communication api_pagination ai_generated true

Jira REST API pagination returns incomplete results or different behavior between v2 and v3

ID: communication/jira-api-pagination-breaking-change

Also available as: JSON · Markdown
82%Fix Rate
85%Confidence
3Evidence
2023-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
any active — — —

Root Cause

Jira REST API v2 and v3 have different pagination behaviors. v2 returns 'total' which can change between pages (as issues are created/modified). v3 sometimes omits 'total'. maxResults is capped server-side (usually 50-100) regardless of requested value.

generic

Workarounds

  1. 92% success Paginate until returned results count < maxResults (not based on 'total') 
    while True: results = jira_search(startAt=offset, maxResults=50); if len(results) < 50: break; offset += 50
  2. 85% success Use JQL with ORDER BY and createdDate filter for stable pagination 
    JQL: 'project = X ORDER BY created ASC' with startAt pagination. Ordering ensures consistent page contents.
  3. 78% success Use Jira's scroll API (experimental) for large result sets 
    For Jira Cloud: use the /search endpoint with 'expand' and pagination tokens instead of offset-based pagination

Dead Ends

Common approaches that don't work:

  1. Set maxResults=1000 to get all issues in one request 88% fail

    Jira server silently caps maxResults to 50-100 (configurable by admin). You get at most 100 results regardless of what you request.

  2. Use 'total' field to determine when pagination is complete 82% fail

    In Jira v3, 'total' may be absent. In v2, 'total' can change between page requests as issues are created/modified mid-pagination.