I'm confused about the number of user records retrievable with the getUsers endpoint

The documentation is confusing me. The “Limitations” section of the Get Users article states:

This endpoint allows you to retrieve a maximum of 1000 users. If your results exceed this threshold, redefine your search.

The fine print under the per_page input box in the “List or search users” section of the API Explorer says:

The amount of entries per page. Default: 50 . Max value: 100

Is it 100 or 1000?

Unfortunately, I don’t (yet) have any apps with >100 users that would allow me to test if the actual per_page limit holds.

Why do I care?

I’m implementing client-side sorting functionality that would allow user records to be sorted on multiple fields. For user searches that yield <=100 users, it makes no difference. However, as soon as I have queries that start yielding >100 users, I’m going to start getting inconsistent, and weird/wrong results.

For example, let’s say I want to sort users first by family_name then by given_name. I can call the getUsers endpoint with sort=family_name:1. Once I get a page of results, I can sort the returned page by given_name. However, imagine that I’m calling this query with the per_page=100, and with these criteria, records 97~103 look as follows:

Record # family_name given_name
97 Johnson Martha
98 Johnson Bill
99 Johnson Susan
100 Johnson George
101 Johnson Alan
102 Johnson Oscar
103 Johnson Michael

The first page of results will sort only the given_name of the records <= 100, so it would sort them: Bill, George, Martha, Susan. Then on the next page of results, we’d start with Alan, who probably should have come on the previous page before Bill.

So, if I know that I have to sort >100 records on >1 field, I can pre-fetch all of the pages, and just sort all 1000 by the multiple fields on the client side.

I realize this is kind of an edge case, and I’m not (yet) at the phase of development when this is critical, but the documentation is confusing. Additionally, this would all be moot if it were possible to send multiple sort criteria to the server. Do you think I should put this in as a feature request?

Hey there!

Sorry for such huge delay in response! We’re doing our best in providing you with best developer support experience out there, but sometimes our bandwidth is not enough comparing to the number of incoming questions.

Wanted to reach out to know if you still require further assistance?

Hi @morphatic - include_totals: true query-param in your API request will tell you how many total results are there. The JSON response includes a total property with a value equal to number of users matching the search query. However, if the query matches more than 1000 users, the total will be reported as 1000.

Also, the limit on per_page query-param is 100.

1 Like

Thanks for providing that knowledge Jatin!