> ## Documentation Index > Fetch the complete documentation index at: https://docs-staging-quickstart-revamp.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Learn how to retrieve lists of users using the get_users endpoint. # Retrieve Users with the Get Users Endpoint The [`GET /api/v2/users` endpoint](https://auth0.com/docs/api/management/v2#!/Users/get_users) allows you to retrieve a list of users. Using this endpoint, you can: * Search based on a variety of criteria * Select the fields to be returned * Sort the returned results This endpoint is **eventually consistent**, and as such, we recommend that you use this endpoint for back office processes such as changing the display name of an existing user. ## Request example To search for users, make a `GET` request to the [`/api/v2/users` endpoint](https://auth0.com/docs/api/management/v2#!/Users/get_users). The request must include a [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens). Pass your search query to the `q` parameter and set the `search_engine` parameter to `v3`. For example, to search for a user whose email is exactly `jane@exampleco.com`, use `q=email:"jane@exampleco.com"`: ```bash cURL lines curl --request GET \ --url 'https://{yourDomain}/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3' \ --header 'authorization: Bearer {yourMgmtApiAccessToken}' ``` ```csharp C# lines var client = new RestClient("https://{yourDomain}/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3"); var request = new RestRequest(Method.GET); request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}"); IRestResponse response = client.Execute(request); ``` ```go Go lines package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://{yourDomain}/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := ioutil.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```java Java lines HttpResponse response = Unirest.get("https://{yourDomain}/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3") .header("authorization", "Bearer {yourMgmtApiAccessToken}") .asString(); ``` ```javascript Node.JS lines var axios = require("axios").default; var options = { method: 'GET', url: 'https://{yourDomain}/api/v2/users', params: {q: 'email:"jane@exampleco.com"', search_engine: 'v3'}, headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'} }; axios.request(options).then(function (response) { console.log(response.data); }).catch(function (error) { console.error(error); }); ``` ```obj-c Obj-C lines #import NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" }; NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3"] cachePolicy:NSURLRequestUseProtocolCachePolicy timeoutInterval:10.0]; [request setHTTPMethod:@"GET"]; [request setAllHTTPHeaderFields:headers]; NSURLSession *session = [NSURLSession sharedSession]; NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) { if (error) { NSLog(@"%@", error); } else { NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response; NSLog(@"%@", httpResponse); } }]; [dataTask resume]; ``` ```php PHP lines $curl = curl_init(); curl_setopt_array($curl, [ CURLOPT_URL => "https://{yourDomain}/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "authorization: Bearer {yourMgmtApiAccessToken}" ], ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; } ``` ```python Python lines import http.client conn = http.client.HTTPSConnection("") headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" } conn.request("GET", "/{yourDomain}/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3", headers=headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` ```ruby Ruby lines require 'uri' require 'net/http' require 'openssl' url = URI("https://{yourDomain}/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true http.verify_mode = OpenSSL::SSL::VERIFY_NONE request = Net::HTTP::Get.new(url) request["authorization"] = 'Bearer {yourMgmtApiAccessToken}' response = http.request(request) puts response.read_body ``` ```swift Swift lines import Foundation let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"] let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` If successful, you'll receive a response like this: ```json lines expandable [ { "email": "jane@exampleco.com", "email_verified": false, "username": "janedoe", "phone_number": "+199999999999999", "phone_verified": false, "user_id": "auth0|5457edea1b8f22891a000004", "created_at": "", "updated_at": "", "identities": [ { "connection": "Initial-Connection", "user_id": "5457edea1b8f22891a000004", "provider": "auth0", "isSocial": false } ], "app_metadata": {}, "user_metadata": {}, "picture": "", "name": "", "nickname": "", "multifactor": [ "" ], "last_ip": "", "last_login": "", "logins_count": 0, "blocked": false, "given_name": "", "family_name": "" } ] ``` ## Query examples Below are some examples of the kinds of queries you can make with the Management API.
Use case Query
Search for all users whose name contains "john" name:\*john\*
Search all users whose name is exactly "jane" name:"jane"
Search for all user names starting with "john" name:john\*
Search for user names that start with "jane" and end with "smith" name:jane\*smith
Search for all users whose email is exactly "[john@exampleco.com](mailto:john@exampleco.com)" email:"[john@exampleco.com](mailto:john@exampleco.com)"
Search for all users whose email is exactly "[john@exampleco.com](mailto:john@exampleco.com)" or "[jane@exampleco.com](mailto:jane@exampleco.com)" using OR email:("[john@exampleco.com](mailto:john@exampleco.com)" OR "[jane@exampleco.com](mailto:jane@exampleco.com)")
Search for users without verified email email\_verified:false OR NOT *exists*:email\_verified
Search for users who have the user\_metadata field named full\_name with the value of "John Smith" user\_metadata.full\_name:"John Smith"
Search for users from a specific connection identities.connection:"google-oauth2"
Search for all users that have never logged in (NOT *exists*:logins\_count OR logins\_count:0)
Search for all users who logged in before 2018 last\_login:\[\* TO 2017-12-31]
Search for all users whose last login was in December 2017 last\_login:\[2017-11 TO 2017-12], last\_login:\[2017-12-01 TO 2017-12-31]
Search for all users with logins count >= 100 and \<= 200 logins\_count:\[100 TO 200]
Search for all users with logins count >= 100 logins\_count:\[100 TO \*]
Search for all users with logins count > 100 and \< 200 logins\_count:\{100 TO 200}
Search for all users whose email domain is "exampleco.com" email.domain:"exampleco.com"
## Limitations * The endpoint returns a maximum of 50 users, even if more users match your query. * If you need to return more than 50 users, use the `page` parameter to show more pages of results. Each page contains 50 users. For example, you can specify `&page=2` to show results 51-100, specify `&page=3` to show results 101-150, and so on. However, this endpoint never returns a total of more than 1000 users with the same search criteria, even with paging. * There is a 1 MB per-user limit on user data that can be indexed, queried, and returned by the [user search endpoint](https://auth0.com/docs/api/management/v2/users/get-users). For more information on how this affects custom metadata larger than 1MB, see [Metadata Field Names and Data Types](/docs/manage-users/user-accounts/metadata/metadata-fields-data#size-limits-and-storage). The [get user endpoint](https://auth0.com/docs/api/management/v2/users/get-users-by-id) must be used to retrieve all user attributes for oversized user profiles. * By default, the `GET /api/v2/users` endpoint returns results in a deterministic order so the same query yields the same logically ordered results each time. This behavior is controlled by the `primary_order` query parameter: * `primary_order=true` (default): results across identical queries are consistently ordered. * `primary_order=false`: results are returned in a non-deterministic order, which can enhance performance for complex queries. * If your application does not require consistent ordering of search results and your queries are short enough not to rely on pagination, set `primary_order=false` to improve query performance. * If you need a complete export of all of your users, use the [export job](https://auth0.com/docs/api/management/v2#!/Jobs/post_users_exports) or the [User Import / Export](/docs/customize/extensions/user-import-export-extension) extension. * If you get the error `414 Request-URI Too Large` this means that your query string is larger than the supported length. In this case, refine your search. We do **not** recommend that you use this endpoint for: * Operations that require immediate consistency. Instead, use the [Get Users by Email endpoint](/docs/manage-users/user-search/retrieve-users-with-get-users-by-email-endpoint) or the [Get Users by ID endpoint](/docs/manage-users/user-search/retrieve-users-with-get-users-by-id-endpoint). * User exports. Instead, use the [User Export endpoint](/docs/manage-users/user-migration/bulk-user-exports). * Operations that require user search as part of authentication processes. Instead, use the Get Users by Email endpoint or the Get Users by ID endpoint. * Searching for Users for [Account Linking](/docs/manage-users/user-accounts/user-account-linking) by Email. Instead, use the Get Users by Email endpoint. ## Learn more * [User Search Query Syntax](/docs/manage-users/user-search/user-search-query-syntax) * [Sort Search Results](/docs/manage-users/user-search/sort-search-results) * [View Search Results by Page](/docs/manage-users/user-search/view-search-results-by-page) * [Bulk User Exports](/docs/manage-users/user-migration/bulk-user-exports) * [Check API Calls](/docs/troubleshoot/authentication-issues/check-api-calls)