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 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 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.

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 indicating 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 you are this property from inside a Rule using the `user` object, its value will be the one 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 indicating if the user has been blocked. Note: `true` only brings back users who are 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.

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 arrays, use the path to the field and ignore the array level. For example, user_metadata.addresses.city:"Paris"

Range and wildcard searches are not available on user metadata fields.

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
C#
Go
Java
Node.JS
Obj-C
...
- PHP
- Python
- Ruby
- Swift

curl --request GET \
  --url 'https://YOUR_DOMAIN/api/v2/users?q=name%3A%22jane%20smith%22&search_engine=v3' \
  --header 'authorization: Bearer YOUR_MGMT_API_ACCESS_TOKEN'

Was this helpful?/

var client = new RestClient("https://YOUR_DOMAIN/api/v2/users?q=name%3A%22jane%20smith%22&search_engine=v3");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN");
IRestResponse response = client.Execute(request);

Was this helpful?/

package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://YOUR_DOMAIN/api/v2/users?q=name%3A%22jane%20smith%22&search_engine=v3"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN")

	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://YOUR_DOMAIN/api/v2/users?q=name%3A%22jane%20smith%22&search_engine=v3")
  .header("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN")
  .asString();

Was this helpful?/

var axios = require("axios").default;

var options = {
  method: 'GET',
  url: 'https://YOUR_DOMAIN/api/v2/users',
  params: {q: 'name:"jane smith"', search_engine: 'v3'},
  headers: {authorization: 'Bearer YOUR_MGMT_API_ACCESS_TOKEN'}
};

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 YOUR_MGMT_API_ACCESS_TOKEN" };

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://YOUR_DOMAIN/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://YOUR_DOMAIN/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 YOUR_MGMT_API_ACCESS_TOKEN"
  ],
]);

$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 YOUR_MGMT_API_ACCESS_TOKEN" }

conn.request("GET", "/YOUR_DOMAIN/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://YOUR_DOMAIN/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 YOUR_MGMT_API_ACCESS_TOKEN'

response = http.request(request)
puts response.read_body

Was this helpful?/

import Foundation

let headers = ["authorization": "Bearer YOUR_MGMT_API_ACCESS_TOKEN"]

let request = NSMutableURLRequest(url: NSURL(string: "https://YOUR_DOMAIN/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?/

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.

Here are some 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.

cURL
C#
Go
Java
Node.JS
Obj-C
...
- PHP
- Python
- Ruby
- Swift

curl --request GET \
  --url 'https://YOUR_DOMAIN/api/v2/users?q=name%3Ajohn*&search_engine=v3' \
  --header 'authorization: Bearer YOUR_MGMT_API_ACCESS_TOKEN'

Was this helpful?/

var client = new RestClient("https://YOUR_DOMAIN/api/v2/users?q=name%3Ajohn*&search_engine=v3");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN");
IRestResponse response = client.Execute(request);

Was this helpful?/

package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://YOUR_DOMAIN/api/v2/users?q=name%3Ajohn*&search_engine=v3"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN")

	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://YOUR_DOMAIN/api/v2/users?q=name%3Ajohn*&search_engine=v3")
  .header("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN")
  .asString();

Was this helpful?/

var axios = require("axios").default;

var options = {
  method: 'GET',
  url: 'https://YOUR_DOMAIN/api/v2/users',
  params: {q: 'name:john*', search_engine: 'v3'},
  headers: {authorization: 'Bearer YOUR_MGMT_API_ACCESS_TOKEN'}
};

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 YOUR_MGMT_API_ACCESS_TOKEN" };

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://YOUR_DOMAIN/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://YOUR_DOMAIN/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 YOUR_MGMT_API_ACCESS_TOKEN"
  ],
]);

$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 YOUR_MGMT_API_ACCESS_TOKEN" }

conn.request("GET", "/YOUR_DOMAIN/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://YOUR_DOMAIN/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 YOUR_MGMT_API_ACCESS_TOKEN'

response = http.request(request)
puts response.read_body

Was this helpful?/

import Foundation

let headers = ["authorization": "Bearer YOUR_MGMT_API_ACCESS_TOKEN"]

let request = NSMutableURLRequest(url: NSURL(string: "https://YOUR_DOMAIN/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?/

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
C#
Go
Java
Node.JS
Obj-C
...
- PHP
- Python
- Ruby
- Swift

curl --request GET \
  --url 'https://YOUR_DOMAIN/api/v2/users?q=logins_count%3A%7B100%20TO%20*%5D&search_engine=v3' \
  --header 'authorization: Bearer YOUR_MGMT_API_ACCESS_TOKEN'

Was this helpful?/

var client = new RestClient("https://YOUR_DOMAIN/api/v2/users?q=logins_count%3A%7B100%20TO%20*%5D&search_engine=v3");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN");
IRestResponse response = client.Execute(request);

Was this helpful?/

package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://YOUR_DOMAIN/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 YOUR_MGMT_API_ACCESS_TOKEN")

	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://YOUR_DOMAIN/api/v2/users?q=logins_count%3A%7B100%20TO%20*%5D&search_engine=v3")
  .header("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN")
  .asString();

Was this helpful?/

var axios = require("axios").default;

var options = {
  method: 'GET',
  url: 'https://YOUR_DOMAIN/api/v2/users',
  params: {q: 'logins_count:{100 TO *]', search_engine: 'v3'},
  headers: {authorization: 'Bearer YOUR_MGMT_API_ACCESS_TOKEN'}
};

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 YOUR_MGMT_API_ACCESS_TOKEN" };

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://YOUR_DOMAIN/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://YOUR_DOMAIN/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 YOUR_MGMT_API_ACCESS_TOKEN"
  ],
]);

$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 YOUR_MGMT_API_ACCESS_TOKEN" }

conn.request("GET", "/YOUR_DOMAIN/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://YOUR_DOMAIN/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 YOUR_MGMT_API_ACCESS_TOKEN'

response = http.request(request)
puts response.read_body

Was this helpful?/

import Foundation

let headers = ["authorization": "Bearer YOUR_MGMT_API_ACCESS_TOKEN"]

let request = NSMutableURLRequest(url: NSURL(string: "https://YOUR_DOMAIN/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?/

Docs