User Search Query Syntax
When searching for users, you can create queries using Lucene query syntax 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
orsmith
.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 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
, andnickname
) are case insensitive. All other fields (including allapp_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 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"
:
curl --request GET \
--url 'https://{yourDomain}/api/v2/users?q=name%3A%22jane%20smith%22&search_engine=v3' \
--header 'authorization: Bearer {yourMgmtApiAccessToken}'
Was this helpful?
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);
Was this helpful?
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))
}
Was this helpful?
HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/users?q=name%3A%22jane%20smith%22&search_engine=v3")
.header("authorization", "Bearer {yourMgmtApiAccessToken}")
.asString();
Was this helpful?
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);
});
Was this helpful?
#import <Foundation/Foundation.h>
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];
Was this helpful?
$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;
}
Was this helpful?
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"))
Was this helpful?
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
Was this helpful?
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()
Was this helpful?
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 withjohn
at the beginning of their names.name:j*
returns all users withj
at the beginning of their names.q=name:john*
returns all users whose names start withjohn
.For suffix matching, literals must have 3 characters or more. For example,
name:*usa
is allowed, butname:*sa
is not.
curl --request GET \
--url 'https://{yourDomain}/api/v2/users?q=name%3Ajohn*&search_engine=v3' \
--header 'authorization: Bearer {yourMgmtApiAccessToken}'
Was this helpful?
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);
Was this helpful?
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))
}
Was this helpful?
HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/users?q=name%3Ajohn*&search_engine=v3")
.header("authorization", "Bearer {yourMgmtApiAccessToken}")
.asString();
Was this helpful?
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);
});
Was this helpful?
#import <Foundation/Foundation.h>
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];
Was this helpful?
$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;
}
Was this helpful?
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"))
Was this helpful?
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
Was this helpful?
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()
Was this helpful?
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 *]
.
curl --request GET \
--url 'https://{yourDomain}/api/v2/users?q=logins_count%3A%7B100%20TO%20*%5D&search_engine=v3' \
--header 'authorization: Bearer {yourMgmtApiAccessToken}'
Was this helpful?
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);
Was this helpful?
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))
}
Was this helpful?
HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/users?q=logins_count%3A%7B100%20TO%20*%5D&search_engine=v3")
.header("authorization", "Bearer {yourMgmtApiAccessToken}")
.asString();
Was this helpful?
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);
});
Was this helpful?
#import <Foundation/Foundation.h>
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];
Was this helpful?
$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;
}
Was this helpful?
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"))
Was this helpful?
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
Was this helpful?
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()
Was this helpful?
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 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
:
{
"favorite_color": "blue",
"approved": false,
"preferredLanguage": "en",
"preferences": {
"fontSize": 13
},
"addresses":{
"city":["Paris","Seattle"]
}
}
Was this helpful?
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
.