How can I search and filter user_metadata/app_metadata in the Management API

Knowledge Articles
, ,
1

Problem statement

Trouble searching and filtering users for the user_metadata and app_metadata in the Management API.

Solution

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, you can use Lucene Search Syntax 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.

See here for the complete list of searchable profile attributes.

Now, to search and filter users, let us use the mock User Profile below.

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.

IMPORTANT: The same queries can be used with the user’s app_metadata.

Reference Materials

5 Likes