> ## Documentation Index
> Fetch the complete documentation index at: https://auth0-chore-events-autoupdate.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Limits and Best Practices for User Search

> Review limits and performance recommendations for user search, and alternatives to the Management API's List or Search Users endpoint by use case.

## List or Search Users Endpoint Alternatives

The Management API's [List or Search Users endpoint](/docs/api/management/v2/users/get-users) (`GET /users`) is not suitable for use in latency-sensitive or correctness-critical paths.

It is eventually consistent, so search results may not reflect very recent writes. It also runs on a short (about 2 second) query time limit on shared infrastructure, so queries can exceed the time limit on large tenants or when under load.

* Do not use the List or Search Users endpoint as part of an authentication process, for [account linking](/docs/manage-users/user-accounts/user-account-linking), or when immediate consistency is necessary. Instead, use the Management API endpoints to [get users by ID or email](/docs/manage-users/user-search/get-users-by-id-or-email).

* Do not use the List or Search Users endpoint to enumerate or export users. Instead, use [bulk user exports](/docs/manage-users/user-migration/bulk-user-exports).

* Do not poll the List or Search Users endpoint or use searches inside login-flow extension points like `post-login` Actions. Instead, [subscribe to Event Streams](/docs/customize/events/sync-data-across-systems) (`user.created`, `user.updated`, `user.deleted`) to keep external systems continuously in sync with user data.

## Performance recommendations

Use the following guidelines for better performance with user search:

* By default, the List or Search Users endpoint returns results in a deterministic order so the same query yields the same logically ordered results each time.

  Non-deterministic search is faster, so if deterministic search is not necessary for your use case, use non-deterministic search by setting `primary_order=false`.

* Escape the space character (for example, write `q=name:John Doe` as `q=name:John\ Doe`).

* Minimize use of wildcards, especially on large data sets. When using wildcards, prefer using them as suffixes to the search term rather than prefixes.

* Prefer filtering or searching on indexed, top-level fields rather than free-form or multi-valued fields (like `app_metadata` and `user_metadata`).

* For user-defined attributes in `app_metadata` and `user_metadata`:

  * Keep metadata fields to 2 KB or less.

  * Use consistent data types and static names for metadata properties.

  * Avoid large schema sizes and deep structures.

* Avoid search criteria that return data sets with more than 1,000 results.

* Avoid existence queries (for example, "give me all users with a property regardless of its value").

## Limits

* Search returns a maximum of 1,000 users, even if more users match your query. When using the API, large results are [paginated](/docs/api/management/v2#pagination).

* Auth0 user profiles have a size limit of 10 KB.

* The List or Search Users endpoint has a [1 MB per-user limit on user data](/docs/manage-users/user-accounts/metadata/metadata-fields-data#user-profile-size-limits) that can be indexed, queried, and returned.

* User profiles that precede the current size limit may be oversized. To retrieve all user attributes for a large user profile, [get users by ID or email](/docs/manage-users/user-search/get-users-by-id-or-email).

* The List or Search Users endpoint does not support sorting by `app_metadata` or `user_metadata`.