GitLab API pagination mode shift: offset-to-keyset default migration uncertainty

Pagination Mode Transition

There is currently no confirmed global timeline for making keyset pagination the default across all GitLab endpoints. Because the migration is handled on a per-endpoint basis to protect database performance, you cannot rely on a consistent default pagination mode across the entire API. Whether the projects listing endpoint defaults to keyset in the next release depends on the specific performance profile of that endpoint in the upcoming version's rollout plan.

Impact on Client Libraries and X-Total Headers

When an endpoint switches to keyset pagination, GitLab omits the X-Total and X-Total-Pages headers. This is a deliberate design choice because calculating the total count of a large dataset is computationally expensive and defeats the performance gains of keyset pagination.

Client libraries that rely on these headers for progress indicators or page-count estimations will experience failures or null values. To adapt, clients must shift from count-based logic to existence-based logic:

• Instead of: Calculating Total / Per Page to determine the number of requests.
• Adopt: Iterating through the next link in the response headers until it is null.

Migration Path for Self-Managed Operators

To align self-managed instances with SaaS-style behavior and ensure client compatibility, operators should encourage the use of explicit pagination parameters rather than relying on defaults. This prevents breaking changes during version upgrades.

Clients should explicitly request the desired mode to maintain stability:

# To force offset pagination (if still supported by the endpoint)
GET /api/v4/projects?pagination=offset&page=1&per_page=20

# To force keyset pagination
GET /api/v4/projects?pagination=keyset

Verification Steps

To verify the current behavior of your specific GitLab version, run the following comparison:

1. Request the projects endpoint using offset pagination: curl --header "PRIVATE-TOKEN: <token>" "https://gitlab.example.com/api/v4/projects?page=1". Note the presence of X-Total.
2. Request the same endpoint using keyset pagination: curl --header "PRIVATE-TOKEN: <token>" "https://gitlab.example.com/api/v4/projects?pagination=keyset". Verify that X-Total is absent.

Diagnostic Detail Required: Are you using a specific GitLab client library (e.g., python-gitlab, glab), or are you making raw HTTP requests? This determines if the fix requires a library update or a change in your internal request logic.