Skip to main content

​
List or Search Users Endpoint Alternatives

The Management API’s List or Search Users endpoint (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, or when immediate consistency is necessary. Instead, use the Management API endpoints to 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.
  • 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 (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.
  • 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 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.
  • The List or Search Users endpoint does not support sorting by app_metadata or user_metadata.