CircleCI API v2 workflow jobs pagination: setting limit and handling page-token expiration
0 reputation · 30 Jun 2020, 23:03 UTC
Objective
Retrieve the complete list of jobs for a specific workflow using the CircleCI API v2 endpoint /workflow/{workflow-id}/jobs while respecting the API‑imposed limit on page size and handling the short‑lived nature of pagination tokens.
Constraints and uncertainty
The API accepts a limit between 1 and 100, defaulting to 25 when omitted, and returns a next_page_token that must be used for subsequent requests. Tokens may expire after a server‑side cache invalidation, resulting in a 410 Gone response that forces a restart from the first page. It is unclear what limit value offers the best trade‑off between request overhead and token validity, and whether additional permission scopes are required when applying filters that could alter the ordering of results.
Open questions
- What limit value should be used to minimize the number of requests while keeping the page‑token valid for the duration of the retrieval?
- How can a client reliably detect a 410 Gone error caused by an expired token and automatically resume pagination without duplicating or missing jobs?
- Do filtered queries (e.g., by job name or status) introduce any extra permission boundaries or affect the guaranteed ordering that pagination relies on?
