Pagination
Paging through large API result sets in SailPoint.
List endpoints return pages; use offset/limit (and count headers) to iterate through large result sets without overloading the API.
- 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.