Pagination
Quick answer
List endpoints return pages; use offset/limit (and count headers) to iterate through large result sets without overloading the API.
Key takeaways
- List endpoints are paginated
- Use limit and offset parameters
- Read total count from headers
- Iterate until all pages are read
List endpoints return results in pages, and you page through them with limit and offset parameters, reading a total-count header to know when to stop. Handling pagination correctly is the difference between an integration that quietly misses records and one that reliably processes the whole population.
How it works
limit sets the page size (how many records per response) and offset sets the starting position. You iterate, increasing the offset by the page size, until you have retrieved everything. The response typically includes a header with the total record count so you know the endpoint of the loop.
GET /v3/accounts?limit=250&offset=0
GET /v3/accounts?limit=250&offset=250
GET /v3/accounts?limit=250&offset=500
# ...continue until offset >= X-Total-CountChoosing a page size
Larger pages mean fewer calls but heavier responses; smaller pages mean more calls and more rate-limit pressure. A moderate page size (a couple of hundred) is usually a good balance. Whatever you choose, do not assume the first page is the whole result, this is the classic pagination bug.
Filter before you page
The cheapest page is the one you never fetch. Apply server-side filtering to shrink the result set before paging through it, so you iterate over hundreds of relevant records rather than tens of thousands of irrelevant ones.
Common pitfalls
- Reading only the first page and treating it as complete.
- Tiny page sizes causing excessive calls and rate limiting.
- Not filtering first, paginating through data you do not need.
Want to learn this properly?
Our live, instructor-led SailPoint Training covers this hands-on, with real projects and a certification path.
Check your understanding
How do you page results?
- A. From a count header returned with the response.
- B. With limit and offset parameters, iterating until all pages are retrieved.
- C. Filter server-side to shrink the result set first.
Show answer
B. With limit and offset parameters, iterating until all pages are retrieved.
With limit and offset parameters, iterating until all pages are retrieved.
How do you know the total?
- A. With limit and offset parameters, iterating until all pages are retrieved.
- B. Filter server-side to shrink the result set first.
- C. From a count header returned with the response.
Show answer
C. From a count header returned with the response.
From a count header returned with the response.
How do you reduce paging work?
- A. Filter server-side to shrink the result set first.
- B. With limit and offset parameters, iterating until all pages are retrieved.
- C. From a count header returned with the response.
Show answer
A. Filter server-side to shrink the result set first.
Filter server-side to shrink the result set first.