<commit_before>---
toc: true
description: This page explains query string syntax, which you can use to construct custom queries when searching using Auth0's Management API.
crews: crew-2
topics:
  - users
  - user-management
  - search
  - query-syntax
contentType:
  - reference
useCase:
  - manage-users
---

# User Search Query Syntax

::: version-warning
This document covers a previous version of user search. We recommend you use [user search v3](/users/search/v3).
:::

This page explains query string syntax, the mini-language used by the Query String Query.

When searching using Auth0's [List or search users](/api/v2/#!/Users/get_users) endpoint, you can construct custom queries using this syntax for the value of the `q` field.

The query string is parsed into a series of *terms* and *operators*. A term can be a single word  (`john` or `smith`) or a phrase surrounded by double quotes (`"<NAME>"`) which will match all the words in the phrase in the same order.

## Searchable fields

You can search for users using the following fields:

* All the [normalized user profile](/users/normalized/auth0/normalized-user-profile-schema) fields

* __Only__ the profile information under the `user_metadata` object:
  - `name`
  - `nickname`
  - `given_name`
  - `family_name`

::: warning
New tenants, starting September 1st 2017, cannot search any of the `app_metadata` fields. Paid tenants (that is, tenants that have a credit card associated in the [Dashboard](${manage_url}/#/tenant/billing/payment)), that were created up to August 31st 2017, can search using the `app_metadata` fields.
:::
For more information, see the [Metadata Overview](/users/concepts/overview-user-metadata).

### Field name examples

Some examples of query string syntax are:

* Where the `created_at` field contains `2016`: `created_at:2016`

* Where the `user_name` field contains `john` or `smith`. If you omit the OR operator the default operator will be used.

    `user_name: (john OR smith)`
    `user_name: (<NAME>)`

* Where the `user_name` field contains the exact phrase `"<NAME>"`: `user_name: "<NAME>"`

* Where the field `nickname` has no value or is missing: `NOT _exists_: nickname`
<commit_msg>Clarify that Search v3 can search by metadata fields<commit_after>---
toc: true
description: This page explains query string syntax, which you can use to construct custom queries when searching using Auth0's Management API.
crews: crew-2
topics:
  - users
  - user-management
  - search
  - query-syntax
contentType:
  - reference
useCase:
  - manage-users
---

# User Search Query Syntax

::: version-warning
This document covers a previous version of user search. We recommend you use [user search v3](/users/search/v3).
:::

This page explains query string syntax, the mini-language used by the Query String Query.

When searching using Auth0's [List or search users](/api/v2/#!/Users/get_users) endpoint, you can construct custom queries using this syntax for the value of the `q` field.

The query string is parsed into a series of *terms* and *operators*. A term can be a single word  (`john` or `smith`) or a phrase surrounded by double quotes (`"<NAME>"`) which will match all the words in the phrase in the same order.

## Searchable fields

You can search for users using the following fields:

* All the [normalized user profile](/users/normalized/auth0/normalized-user-profile-schema) fields

* __Only__ the profile information under the `user_metadata` object:
  - `name`
  - `nickname`
  - `given_name`
  - `family_name`

::: warning
New tenants, starting September 1st 2017, cannot search any of the `app_metadata` fields. Paid tenants (that is, tenants that have a credit card associated in the [Dashboard](${manage_url}/#/tenant/billing/payment)), that were created up to August 31st 2017, can search using the `app_metadata` fields.
Note that [Search v3](/users/search/v3/query-syntax) does not have this restriction.
:::
For more information, see the [Metadata Overview](/users/concepts/overview-user-metadata).

### Field name examples

Some examples of query string syntax are:

* Where the `created_at` field contains `2016`: `created_at:2016`

* Where the `user_name` field contains `john` or `smith`. If you omit the OR operator the default operator will be used.

    `user_name: (john OR smith)`
    `user_name: (<NAME>)`

* Where the `user_name` field contains the exact phrase `"<NAME>"`: `user_name: "john smith"`

* Where the field `nickname` has no value or is missing: `NOT _exists_: nickname`

{'fraction_non_alphanumeric': 0.09681697612732096, 'fraction_numerical': 0.01215738284703802, 'mean_word_length': 4.355029585798817, 'pattern_counts': {'":': 0, '<': 10, '<?xml version=': 0, '>': 10, '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': '2125743', 'n_tokens_mistral': 1393, 'n_tokens_neox': 1292, 'n_words': 584}