Retrieve users by role paginated and filtered by name/email

I want to retrieve users by role which must be paginated (with the page request object) using this endpoint GET /api/v2/roles/{id}/users.
But I also would like to further filter them by email/name or nickname. Basically I would like to pass a UserFilter to the above endpoint so I can filter them accordingly. How could I achieve that?

Hi @tgramova

There is no documented filter for the GET /api/v2/roles/{id}/users call, other than the pagination parameters (or checkpoints).

However, the response contains a “name” field and an “email” one, so you can use one of these or both to filter locally. The only downside is that you will still need to grab the records from the server, but it would work.

For example, in Python, something like:

for user in response:
	name = response[user]["name"]
	email = response[user]["email"]
	if 'john' in name: # or in email

Another option would be to use a different endpoint: GET /api/v2/users-by-email (documented here) which allows you to get users using the email address, and then perform a second call to GET /api/v2/users/{id}/roles with the User id, to get the user’s roles. Depending on the amount of users and your use-case, this could be more efficient despite the second call.

This would also work with GET /api/v2/users and a query, which would allow you to search on other fields such as name, email, nickname etc. This endpoint is documented here and the Query syntax here. (use the “q” field)


Hi @sylvainf
Thank you very much for your quick response.
The challenge I have is that I need the users to be paginated by 10 per page.
So the following scenario wont work with the suggested approaches →
Filter first 10 users with role ‘basic’ (but there are 15 in total in the database let’s say) and then further filter by name → I will only get 5 out of 10 (not 15) which wont be relevant as there could be more in the other ones which are not returned for the first page.
Let me know if that makes sense.

The point in paginating is to limit the results per page to avoid overloading the server and your client. Nothing prevents you from making a subsequent call (using page=2 etc.) until the last page is reached. Use the “include_totals” field to know how many user objects you get, and divide by your per_page value to know how many pages you need to query. Store your results in a local collection or wherever suits.

Could you share some details about your use case, what goal are you trying to achieve?

Yes, sure.
So we have role filter on our client side. We want to be able to filter by roles and within the returned results to filter by name/email and limit the results to 10 per page.
So first we have 10 out of 50 users with the selected role ‘base_user’ returned. Then on the next step we want to filter only users with name John from this 50 users with the selected role. And they are 15 for example but I want to show them 10 per page still.
How can I achieve that?

The most robust way I can think of is to build a middleware service using our API and then providing your own filter. On the Auth0 side you will have to pick the method that suits best for your use case (depends on the number of roles, users and users per role):

1 - /api/v2/roles/{id}/users: query users by role (with pagination) > parse response to filter by name/email.
2 - /api/v2/users: query users using a querystring (‘q’ parameter) to narrow results down by name/email, then perform a second call to get corresponding roles.

Store the results in a temporary object / DB and access it via your own client/GUI.

A second method that I can think of (but I haven’t tested) is to add your user’s roles as metadata. You can then use metadata to query the users as explained here. This would allow you to use my method 2 above but with only one call per role (or less)

If you’d like to request the addition of a name / email or query filter on the Role API, I would suggest you doing it here.

1 Like