Problem Statement
When calling out the Management API endpoint /api/v2/roles/{id}/users in order to paginate over all the users assigned to a role, after requesting a certain number of pages, we received a 400 status code with below error.
Requesting page 10 exceeds the allowed maximum of 1000 records. To fetch results beyond 1000, use the checkpoint pagination method.
Cause
The request to the endpoint uses offset pagination (page and per_page parameters). This type of pagination is limited to returning only 1000 records. Therefore, requesting page N will throw an error if the following condition is TRUE:
N * RPP + RPP > 1000
N is the page index being requested
RPP is the number of records per page being requested
For example, when requesting 100 records per page, the error will be thrown when the page index is 10.
The above logic is independent of the actual number of records (users) associated with the role. Even if the role has less than 1000 users associated with it, the endpoint will report an error if the request of the page index goes over the maximum.
Solution
In order to call this endpoint and paginate over more than 1000 records, the checkpoint pagination (from and take parameters) approach must be used.
Reference
https://auth0.com/docs/api/management/v2#!/Roles/get_role_user