Retrieve Users with the Get Users Endpoint

The GET /api/v2/users endpoint 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. The request must include a Management API access token. 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":




  

    
  


  
  

    
      

        
curl --request GET \
  --url 'https://{yourDomain}/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3' \
  --header 'authorization: Bearer {yourMgmtApiAccessToken}'
Was this helpful?
/

      

    
      

        
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);
Was this helpful?
/

      

    
      

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

}
Was this helpful?
/

      

    
      

        
HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/users?q=email%3A%22jane%40exampleco.com%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: '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);
});
Was this helpful?
/

      

    
      

        
#import <Foundation/Foundation.h>

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];
Was this helpful?
/

      

    
      

        
$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;
}
Was this helpful?
/

      

    
      

        
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"))
Was this helpful?
/

      

    
      

        
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
Was this helpful?
/

      

    
      

        
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()
Was this helpful?
/

      

    
  





If successful, you'll receive a response like this:
[
  {
    "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": ""
  }
]
Was this helpful?
/


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"
email:"john@exampleco.com"




Search for all users whose email is exactly "john@exampleco.com" or "jane@exampleco.com" using OR
email:("john@exampleco.com" OR "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. For more information on how this affects custom metadata larger than 1MB, see Metadata Field Names and Data Types. The get user endpoint must be used to retrieve all user attributes for oversized user profiles.
If you need a complete export of all of your users, use the export job or the User Import / Export 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:
Learn more