Skip to main content
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.
  • Operators should always be capitalized.

​
Searchable fields

You can search for users using all the normalized user profile fields and the fields below: 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 in arrays, use the path to the field and ignore the array level. For example, user_metadata.addresses.city:"Paris"
Metadata fields that contain an empty array, empty object, or null value are not indexed and cannot be searched for. Range and wildcard searches are not available on user_metadata fields.

​
Exact match

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":

​
Wildcards

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.

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

​
Ranges

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

​
Searchable Profile Attribute Examples

When searching for users in the Auth0 , you can filter users by user_metadata or app_metadata. To do so, you can use Lucene Search Syntax with the q parameter. Because the Auth0 Management API list or the search users endpoint is limited to 1000 results (10 pages of 100 records), filtering is a useful way of ensuring that the most relevant results are returned. Below is a sample of a user profile user_metadata:

​
Filter metadata attributes

To return a user_metadata value, update the q query with a filter for the attribute. For user_metadata values, you can query the profile directly: q: _exists_:user_metadata.fav_color This query returns all user profiles with the fav_color attribute in the user_metadata.

​
Filter metadata nested object attributes and values

You can also search on nested objects in user_metadata: q: _exists_:user_metadata.preferences.fontSize This queries all user profiles with preferences.fontSize configured in the user_metadata. To search for the values of a nested object from another object, review the query below: q: user_metadata.preferences.fontSize:13 This query returns all user profiles that match the fontSize attribute with the value of 13.

​
Filter metadata nested array values

You can use the query below to search fields in nested arrays: q: user_metadata.addresses.city:"Seattle" This returns all user profiles that return the value of Seattle from the address.city attributes in the user_metadata.

​
Learn more