<commit_before>---
name: User Search
description: Best practices when searching for users in Auth0
toc: true
---
# User Search

Auth0 provides multiple endpoints you can use to retrieve users. Each one offers slightly different functionality, and in this document, we'll cover the best practices for using each of the endpoints.

## User Search Options

Currently, Auth0 offers three different ways by which you can search for users:

* [Users](#users)
* [Users by ID](#users-by-id)
* [Users by Email](#users-by-email)
* [User Export](#user-export)

::: note
The following sections contain examples on how to call the various user search endpoints. To do so, you'll need to obtain a valid [access token](/api/management/v2/tokens) and provide it in the header of your call (simply replace the `YOUR_MGMT_API_ACCESS_TOKEN` placeholder value).
:::

### Definitions

In this document, we use the terms **eventually consistent** and **immediately consistent**.

* **Eventually consistent**: When you request information about a user (or a group of users), the response might not reflect the results of a recently-complete write operation. However, if you repeat your request after a short period of time, the response will return up-to-date data.

* **Immediately consistent**: When you request information about a user (or a group of users), the response will reflect the results of all successful write operations, including those that occured shortly prior to your request.

## Users

The [`GET /api/v2/users` endpoint](/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

*Required Scopes*: `read:users`

```har
{
	"method": "GET",
	"url": "https://${account.namespace}/api/v2/users",
	"headers": [{
		"name": "Authorization",
		"value": "Bearer YOUR_MGMT_API_ACCESS_TOKEN"
	}]
}
```

**Sample Response**

Successful calls to the endpoint returns a JSON object similar to the following:

```json
[
  {
    "email": "<EMAIL>",
    "email_verified": false,
    "username": "johndoe",
    "phone_number": "+199999999999999",
    "phone_verified": false,
    "user_id": "usr_5457edea1b8f33391a000004",
    "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": ""
  }
]
```

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.

We do **not** recommend that you use this endpoint for:

* Operations that require immediate consistency - please use the [Users by Email endpoint](#users-by-email) or the [Users by ID endpoint](#users-by-id) for such actions
* User exports - please use the [User Export endpoint](#user-export) for such actions
* Operations that require user search as part of the Authentication Pipeline - please use the [Users by Email endpoint](#users-by-email) or the [Users by ID endpoint](#users-by-id) for such actions
* Searching for Users for [Account Linking](/link-accounts) by Email - please use the [Users by Email endpoint](#users-by-email) or the [Users by ID endpoint](#users-by-id) for such actions

## Users by ID

The [`GET /api/v2/users/{id}` endpoint](/api/management/v2#!/Users/get_users_by_id) allows you to retrieve a specific user using their Auth0 user ID.

*Required Scopes*: `read:users`

```har
{
	"method": "GET",
	"url": "https://${account.namespace}/api/v2/users/USER_ID",
	"headers": [{
		"name": "Authorization",<commit_msg>Fix error<commit_after>---
name: User Search
description: Best practices when searching for users in Auth0
toc: true
---
# User Search

Auth0 provides multiple endpoints you can use to retrieve users. Each one offers slightly different functionality, and in this document, we'll cover the best practices for using each of the endpoints.

## User Search Options

Currently, Auth0 offers three different ways by which you can search for users:

* [Users](#users)
* [Users by ID](#users-by-id)
* [Users by Email](#users-by-email)
* [User Export](#user-export)

::: note
The following sections contain examples on how to call the various user search endpoints. To do so, you'll need to obtain a valid [access token](/api/management/v2/tokens) and provide it in the header of your call (simply replace the `YOUR_MGMT_API_ACCESS_TOKEN` placeholder value).
:::

### Definitions

In this document, we use the terms **eventually consistent** and **immediately consistent**.

* **Eventually consistent**: When you request information about a user (or a group of users), the response might not reflect the results of a recently-complete write operation. However, if you repeat your request after a short period of time, the response will return up-to-date data.

* **Immediately consistent**: When you request information about a user (or a group of users), the response will reflect the results of all successful write operations, including those that occured shortly prior to your request.

## Users

The [`GET /api/v2/users` endpoint](/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

*Required Scopes*: `read:users`

```har
{
	"method": "GET",
	"url": "https://${account.namespace}/api/v2/users",
	"headers": [{
		"name": "Authorization",
		"value": "Bearer YOUR_MGMT_API_ACCESS_TOKEN"
	}]
}
```

**Sample Response**

Successful calls to the endpoint returns a JSON object similar to the following:

```json
[
  {
    "email": "<EMAIL>",
    "email_verified": false,
    "username": "johndoe",
    "phone_number": "+199999999999999",
    "phone_verified": false,
    "user_id": "usr_5457edea1b8f33391a000004",
    "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": ""
  }
]
```

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.

We do **not** recommend that you use this endpoint for:

* Operations that require immediate consistency - please use the [Users by Email endpoint](#users-by-email) or the [Users by ID endpoint](#users-by-id) for such actions
* User exports - please use the [User Export endpoint](#user-export) for such actions
* Operations that require user search as part of the Authentication Pipeline - please use the [Users by Email endpoint](#users-by-email) or the [Users by ID endpoint](#users-by-id) for such actions
* Searching for Users for [Account Linking](/link-accounts) by Email - please use the [Users by Email endpoint](#users-by-email) for such actions

## Users by ID

The [`GET /api/v2/users/{id}` endpoint](/api/management/v2#!/Users/get_users_by_id) allows you to retrieve a specific user using their Auth0 user ID.

*Required Scopes*: `read:users`

```har
{
	"method": "GET",
	"url": "https://${account.namespace}/api/v2/users/USER_ID",
	"headers": [{
		"name": "Authorization",
{'fraction_non_alphanumeric': 0.12348942598187311, 'fraction_numerical': 0.015609264853977844, 'mean_word_length': 4.145725388601036, 'pattern_counts': {'":': 68, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 2, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4505638', 'n_tokens_mistral': 2409, 'n_tokens_neox': 2283, 'n_words': 912}