I’m building a lab exercise for my advanced training class to teach students how to interact with the API. The task is simple: write a script to dump the entire user directory (about 5,000 users) into a CSV using GET /api/v2/users.
My students keep hitting a 400 error when their loop tries to request pageNumber=100 (assuming pageSize=50). The error says the requested page exceeds the maximum allowed offset. I checked the documentation and indeed, there seems to be a hard limit on deep pagination for this endpoint. What is the best practice for retrieving a full directory of 10,000+ users if we can’t paginate past a certain point?
We have over 12,000 agents in our APAC region, so we hit this immediately!
The GET /api/v2/users endpoint is designed for UI searches, not bulk data extraction. It limits you to the first few thousand records to protect the search index. To get the entire directory, you shouldn’t use pagination at all. Instead, use the ‘Search’ API (POST /api/v2/users/search) with a cursor. Cursor-based pagination allows you to stream the entire dataset without hitting the offset limit, because it passes a pointer to the next record rather than calculating a deep page number.
The point above is correct about the Search API, but there’s an even better way for pure data extraction that I use for our network topology maps.
Use the ‘User Bulk Export’ API (POST /api/v2/users/bulk). You submit a job, the platform generates a CSV of all users asynchronously in the background, and then gives you an S3 download URI. It’s infinitely faster than writing a loop with cursor pagination, and it uses zero API rate limits against your application! Definitely teach your students the bulk APIs for heavy lifting.