How to Search and Filter User Metadata and App Metadata in the Management API
This article explains how to search for users based on user_metadata and app_metadata fields using the Auth0 Management API. It details the correct query syntax required to filter users by the existence of a metadata key or by a specific value within the metadata, including nested objects and arrays.
-
Auth0 Management API
-
User Metadata
-
App Metadata
When searching for users in the Auth0 Management API, there is the option to filter them by the user_metadata or app_metadata. To do so, Lucene Search Syntax can be used in the 'q' parameter to filter for these users.
This is useful since Auth0 Management API List or Search Users endpoint is limited to 1000 results (10 pages of 100 records). This way, the results return up to 1000 of the most relevant results.
Refer to the User Profile Structure docs for the complete list of searchable profile attributes.
Sample User Profile user_metadata:
{
"favorite_color": "blue",
"approved": false,
"preferredLanguage": "en",
"preferences": {
"fontSize": 13
},
"addresses":{
"city":["Paris","Seattle"]
}
}Below are several ways to query for the user’s user_metadata/app_metadata.
Usage 1: Search user_metadata value
q: _exists_:user_metadata.fav_color
Returns all user profiles that have fav_color in the user_metadata.
Usage 2: Search on Nested Objects in user_metadata
q: _exists_:user_metadata.preferences.fontSize
Returns all user profiles that have preferences.fontSize configured in the user_metadata.
Usage 3: Search on a scalar value nested in another object
q: user_metadata.preferences.fontSize:13
Returns all user profiles that match the fontSize : 13 in the user_metadata.
Usage 4: Search fields in objects nested arrays
q: user_metadata.addresses.city:”Seattle”
Returns all user profiles that match the addresses.city:”Seattle” in the user_metadata.
Note: The same queries can be used with the user’s app_metadata.
