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

## General Principles

When running user searches:

* Use an immediately consistent endpoint during authentication pipeline
* Try to use exact match searches (with the `raw` subfield) whenever possible
* Avoid existence queries (for example, "give me all users with a property regardless of its value")
* Avoid full text search or partial searches
* Avoid polling the search APIs
* Avoid using large metadata field (try to keep metadata fields to 2 KB or less)
* Use a well-known schema for metadata:
  * Use consistent data types for properties
  * Avoid dynamic property names
  * Avoid large schema sizes and deep structures
  * Avoid storing data you do not need for authentication and authorization purposes

## 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<commit_msg>Fix formatting<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.

## General Principles

When running user searches:

* Use an immediately consistent endpoint during authentication pipeline
* Use exact match searches (with the `raw` subfield) whenever possible
* Use a well-known schema for metadata:
  * Use consistent data types for properties
  * Avoid dynamic property names
  * Avoid large schema sizes and deep structures
  * Avoid storing data you do not need for authentication and authorization purposes
  
Avoid:

* Existence queries (for example, "give me all users with a property regardless of its value")
* Full text search or partial searches
* Polling the search APIs
* Using large metadata field (try to keep metadata fields to 2 KB or less)

## 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
{'fraction_non_alphanumeric': 0.06760388670663635, 'fraction_numerical': 0.002894356005788712, 'mean_word_length': 4.685076380728555, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, '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': '4477628', 'n_tokens_mistral': 1207, 'n_tokens_neox': 1152, 'n_words': 675}