> ## 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. > Describes Auth0's user search query string syntax. # User Search Query Syntax This content describes the current Auth0 user search, version 3. When searching for users, you can create queries using [Lucene query syntax](http://www.lucenetutorial.com/lucene-query-syntax.html) to refine your search. The query string is parsed into a series of terms and operators: * A term can be a single word such as `jane` or `smith`. * A term can be a phrase surrounded by double quotes (`"green apple"`), which will match all words in the phrase in the same order. * A term without a field name will not match text in the [user metadata](/docs/manage-users/user-accounts/metadata) fields. * Multiple terms can be grouped together with parentheses to form sub-queries. * Search values for the normalized user fields (`email`, `name`, `given_name`, `family_name`, and `nickname`) are case insensitive. All other fields (including all `app_metadata`/`user_metadata` fields) are case sensitive. * Operators (`AND`, `OR`, `NOT`) work on all normalized user fields and root metadata fields. * Operators should always be capitalized. ## Searchable fields You can search for users using all the [normalized user profile fields](/docs/manage-users/user-accounts/user-profiles/normalized-user-profile-schema) and the fields below:
Search Field Data Type Description
phone\_number text The user's phone number. Only valid for users with SMS connections.
phone\_verified boolean The true/false value indicates whether the user's phone number has been verified. Only valid for users with SMS connections.
logins\_count integer The number of times the user has logged in. If a user is blocked and logs in, the blocked session is counted in logins\_count and updates the last\_login value.
created\_at date time The timestamp of when the user profile was first created.
updated\_at date time The timestamp of when the user's profile was last updated/modified.
last\_login date time The timestamp of when the user last logged in. In case this property executes from inside a Rule with the user object, the value will be associated with the login that triggered the rule (since rules execute after the actual login).
last\_ip text (valid IP address) The IP address associated with the user's last login.
blocked boolean The true or false value indicates if the user has been blocked. Note: true only brings back users blocked via the Admin Dashboard and Management API; it does not bring back users blocked by brute force anomaly detection.
email.domain text The domain part of the user's email.
organization\_id text (valid organization ID) The organization that the user is a member of
Metadata fields may be used with: * boolean * numeric: integer or double * text * objects: in order to search a scalar value nested in another object, use the path to the field. For example, `app_metadata.subscription.plan:"gold"` * arrays: in order to search fields in objects nested in arrays, use the path to the field and ignore the array level. For example, `user_metadata.addresses.city:"Paris"` Metadata fields that contain an empty array, empty object, or `null` value are not indexed and cannot be searched for. Range and wildcard searches are not available on `user_metadata` fields. ## Exact match To find exact matches, use double quotes: `name:"jane smith"`. For example, to find users with the name `jane smith`, use `q=name:"jane smith"`: ```bash cURL lines curl --request GET \ --url 'https://{yourDomain}/api/v2/users?q=name%3A%22jane%20smith%22&search_engine=v3' \ --header 'authorization: Bearer {yourMgmtApiAccessToken}' ``` ```csharp C# lines var client = new RestClient("https://{yourDomain}/api/v2/users?q=name%3A%22jane%20smith%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=name%3A%22jane%20smith%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=name%3A%22jane%20smith%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: 'name:"jane smith"', 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=name%3A%22jane%20smith%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=name%3A%22jane%20smith%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=name%3A%22jane%20smith%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=name%3A%22jane%20smith%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=name%3A%22jane%20smith%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() ``` ## Wildcards Wildcard searches can be run on terms using the asterisk character (`*`) to replace zero or more characters. Wildcard searches are not available on `user_metadata` fields. #### Examples * `name:john*` returns all users with `john` at the beginning of their names. * `name:j*` returns all users with `j` at the beginning of their names. * `q=name:john*` returns all users whose names start with `john`. * For suffix matching, literals must have 3 characters or more. For example, `name:*usa` is allowed, but `name:*sa` is not. ```bash cURL lines curl --request GET \ --url 'https://{yourDomain}/api/v2/users?q=name%3Ajohn*&search_engine=v3' \ --header 'authorization: Bearer {yourMgmtApiAccessToken}' ``` ```csharp C# lines var client = new RestClient("https://{yourDomain}/api/v2/users?q=name%3Ajohn\*&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=name%3Ajohn*&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=name%3Ajohn*&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: 'name:john*', 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=name%3Ajohn*&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=name%3Ajohn*&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=name%3Ajohn*&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=name%3Ajohn*&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=name%3Ajohn*&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() ``` ## Ranges You can use ranges in your user search queries. Range searches are not available on user metadata fields. * For inclusive ranges, use square brackets: `[min TO max]`. * For exclusive ranges, use curly brackets: `{min TO max}`. * Curly and square brackets can be combined in the same range expression: `logins_count:[100 TO 200}`. * Use ranges in combination with wildcards. For example, to find all users with more than 100 logins, use `q=logins_count:{100 TO *]`. ```bash cURL lines curl --request GET \ --url 'https://{yourDomain}/api/v2/users?q=logins_count%3A%7B100%20TO%20*%5D&search_engine=v3' \ --header 'authorization: Bearer {yourMgmtApiAccessToken}' ``` ```csharp C# lines var client = new RestClient("https://{yourDomain}/api/v2/users?q=logins_count%3A%7B100%20TO%20\*%5D&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=logins_count%3A%7B100%20TO%20*%5D&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=logins_count%3A%7B100%20TO%20*%5D&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: 'logins_count:{100 TO *]', 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=logins_count%3A%7B100%20TO%20*%5D&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=logins_count%3A%7B100%20TO%20*%5D&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=logins_count%3A%7B100%20TO%20*%5D&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=logins_count%3A%7B100%20TO%20*%5D&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=logins_count%3A%7B100%20TO%20*%5D&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() ``` ## Searchable Profile Attribute Examples When searching for users in the Auth0 Management API, you can filter users by `user_metadata` or `app_metadata`. To do so, you can use Lucene Search Syntax with the `q` parameter. Because the Auth0 Management API [list or the search users](https://auth0.com/docs/api/management/v2#!/Users/get_users) endpoint is limited to 1000 results (10 pages of 100 records), filtering is a useful way of ensuring that the most relevant results are returned. Below is a sample of a user profile `user_metadata`: ```json lines { "favorite_color": "blue", "approved": false, "preferredLanguage": "en", "preferences": { "fontSize": 13 }, "addresses":{ "city":["Paris","Seattle"] } } ``` ### Filter metadata attributes To return a `user_metadata` value, update the `q` query with a filter for the attribute. For `user_metadata` values, you can query the profile directly: `q: _exists_:user_metadata.fav_color` This query returns all user profiles with the `fav_color` attribute in the `user_metadata`. ### Filter metadata nested object attributes and values You can also search on nested objects in `user_metadata`: `q: _exists_:user_metadata.preferences.fontSize` This queries all user profiles with `preferences.fontSize` configured in the `user_metadata`. To search for the values of a nested object from another object, review the query below: `q: user_metadata.preferences.fontSize:13` This query returns all user profiles that match the `fontSize` attribute with the value of `13`. ### Filter metadata nested array values You can use the query below to search fields in nested arrays: `q: user_metadata.addresses.city:"Seattle"` This returns all user profiles that return the value of `Seattle` from the `address.city` attributes in the `user_metadata`. ## Learn more * [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) * [Retrieve Users with the Get Users Endpoint](/docs/manage-users/user-search/retrieve-users-with-get-users-endpoint)