Question
Jenkins REST API Pagination: Inconsistent Parameters Across Endpoints
Sora Maple
0 reputation · 12 Dec 2022, 09:22 UTC
17.3K views
Loading…
0 reputation · 12 Dec 2022, 09:22 UTC
When retrieving large job or build collections via the Jenkins REST API, the goal is to bound the query and paginate results to avoid excessive payloads and controller load. However, the API exposes multiple pagination mechanisms that vary by endpoint. The classic /api/json endpoint supports a tree parameter for field filtering and depth control, while job-specific endpoints accept offset and limit for build lists. Blue Ocean’s /blue/rest/ API uses a cursor‑based start and limit scheme, and plugin‑provided endpoints sometimes ignore standard pagination parameters entirely. There is no global configuration to enforce consistent limits or a unified pagination contract across the platform.
This inconsistency creates uncertainty about which parameters to use for a given query, how to reliably bound nested collections, and whether performance regressions will occur as offsets grow large. It also raises questions about future compatibility as Jenkins core and plugins evolve.
What are the documented best‑practice guidelines for selecting pagination parameters across different Jenkins REST API endpoints? How can a client reliably detect and adapt to endpoint‑specific pagination limits without hard‑coding values? Should Jenkins core introduce a unified pagination interface for all API consumers?
33275 reputation · 12 Dec 2022, 15:03 UTC
Because Jenkins lacks a unified pagination contract, the correct parameters depend entirely on the specific API surface being accessed. There are no global guidelines; instead, you must match the parameter to the endpoint's underlying implementation.
The classic Remote API does not support offset or limit for most top-level collections. To bound results and reduce controller load, use the tree parameter with range syntax:
jenkins?tree=jobs[0-10] to retrieve only the first 11 jobs.?tree=jobs[0-10]{name,url}.Endpoints targeting build histories typically support start and limit parameters. These are the most reliable for iterating through build records of a single project.
This modern interface utilizes a cursor-based approach. Use start and limit, but be aware that the response structure differs significantly from the classic Remote API.
Since Jenkins does not provide a Link header or a total_count field consistently across all endpoints, clients cannot automatically detect limits. To adapt reliably, implement a Probe-and-Iterate pattern:
[0-9]).[10-19], [20-29]) until the boundary is hit.This approach assumes a relatively stable dataset during the fetch process. Be aware of the following technical constraints:
limit values. Large JSON serializations can trigger OutOfMemoryError on the Jenkins controller.[0-10]) may skip or duplicate entries.limit.Test range-based filtering on your instance using curl:
curl -u user:token "http://jenkins-server/api/json?tree=jobs[0-5]"Diagnostic Detail Needed: Are you primarily targeting core Jenkins job/build lists, or are you interacting with specific plugin-provided endpoints (e.g., Pipeline Stage View)? The latter may require custom query parameters unique to that plugin.
Use comments to ask for clarification. Post a solution as an answer.
33,275 reputation · 12 Dec 2022, 17:05 UTC
When iterating build histories with offset and limit, large offsets can still impose significant controller load. The underlying storage may scan skipped records before returning the requested page, so bounding the response size does not necessarily bound the work done on the controller. This effect becomes more pronounced as job histories grow.
For plugin-provided endpoints, treat pagination parameters as advisory until verified. Some endpoints silently ignore unknown parameters and return the full collection, which can turn a bounded request into an unbounded payload. A practical safeguard is to compare the returned array length against the requested limit and abort if the server ignored the bound.
Where deep pagination is unavoidable, keep page sizes modest and rely on tree field filtering to reduce payload size rather than assuming a large offset is cheap. Always verify behavior against your specific Jenkins and plugin versions, since pagination semantics can change independently of core releases.