> ## Documentation Index
> Fetch the complete documentation index at: https://stytch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Search Users
> Search for Users within your Stytch Project.
export const userTip = "Represents an end user's account in your application.";
This endpoint is not recommended for use in login flows. Scaling issues may occur, as search performance may vary from \~150 milliseconds to 9 seconds depending on query complexity and rate limits are set to 150 requests/minute.
Search for Users within your Stytch Project.
Submitting an empty `query` returns all Users for your Project.
## Filter Reference
Each query operand requires a `filter_name` and `filter_value`. The table below shows all available filters, their value types, and descriptions.
| Filter Name | Value Type | Description | Example |
| --------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `created_at_between` | `object` | Filter users created between two timestamps. Object must contain `greater_than` and `less_than` timestamp strings in RFC 3339 format (UTC). | `{"greater_than": "2021-12-29T12:33:09Z", "less_than": "2022-01-15T12:33:09Z"}` |
| `created_at_greater_than` | `string` | Filter users created after the specified timestamp in RFC 3339 format (UTC). | `"2021-12-29T12:33:09Z"` |
| `created_at_less_than` | `string` | Filter users created before the specified timestamp in RFC 3339 format (UTC). | `"2022-01-15T12:33:09Z"` |
| `user_id` | `array[string]` | Filter by one or more exact user IDs. | `["user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"]` |
| `full_name_fuzzy` | `string` | Fuzzy search for full or prefixed name match. Matches prefix of first or last name (e.g., "Ada" matches "Ada Lovelace" or "Abigail Adams"). | `"Ada"` |
| `status` | `string` | Filter users by status: `active` or `pending`. See [create\_user\_as\_pending](/docs/api/create-user) for more context. | `"active"` |
| `phone_number` | `array[string]` | Filter by one or more exact phone numbers in E.164 format (e.g., +1XXXXXXXXXX). | `["+12025550162"]` |
| `phone_number_fuzzy` | `string` | Fuzzy search for partial phone number match (e.g., returns all users with "415" in their phone number). | `"415"` |
| `phone_id` | `array[string]` | Filter by one or more exact phone IDs. | `["phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0"]` |
| `phone_verified` | `boolean` | Filter users by whether they have a verified phone number (i.e., phone number used to successfully authenticate). | `true` |
| `email_address` | `array[string]` | Filter by one or more exact email addresses. | `["ghopper@stytch.com"]` |
| `email_address_fuzzy` | `string` | Fuzzy search for partial email address match. Matches prefixes of address or domain (e.g., "ada" matches [ada.lovelace@stytch.com](mailto:ada.lovelace@stytch.com) and [grace@ada.com](mailto:grace@ada.com), but not [sarah.adamson@stytch.com](mailto:sarah.adamson@stytch.com)). Use domain prefix to filter by domain (e.g., "gmail" returns all gmail.com users). | `"ada"` |
| `email_id` | `array[string]` | Filter by one or more exact email IDs. | `["email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"]` |
| `email_verified` | `boolean` | Filter users by whether they have a verified email address (i.e., email used to successfully authenticate). | `true` |
| `oauth_provider` | `array[string]` | Filter users by OAuth provider(s) they've authenticated with. | `["Google", "Apple"]` |
| `webauthn_registration_id` | `array[string]` | Filter by one or more exact WebAuthn registration IDs. | `["webauthn-registration-test-5c44cc6a-8af7-48d6-8da7-ea821342f5a6"]` |
| `webauthn_registration_verified` | `boolean` | Filter users by whether they have successfully registered a Passkey or WebAuthn device. | `true` |
| `biometric_registration_id` | `array[string]` | Filter by one or more exact biometric registration IDs. | `["biometric-registration-test-6966a6fc-5264-46ee-9ba4-98c6322a5134"]` |
| `biometric_registration_verified` | `boolean` | Filter users by whether they have successfully registered their biometrics. | `true` |
| `totp_id` | `array[string]` | Filter by one or more exact TOTP IDs. | `["totp-test-81bf03a8-86e1-4d95-bd44-bb3495224953"]` |
| `totp_verified` | `boolean` | Filter users by whether they have a verified TOTP (i.e., TOTP used to successfully authenticate). | `true` |
| `crypto_wallet_id` | `array[string]` | Filter by one or more exact crypto wallet IDs. | `["crypto-wallet-test-81bf03a8-86e1-4d95-bd44-bb3495224953"]` |
| `crypto_wallet_address` | `array[string]` | Filter by one or more exact crypto wallet addresses. | `["0x6df2dB4Fb3DA35d241901Bd53367770BF03123f1"]` |
| `crypto_wallet_verified` | `boolean` | Filter users by whether they have a verified crypto wallet (i.e., wallet used to successfully authenticate). | `true` |
| `password_exists` | `boolean` | Filter users by whether they have a password set. | `true` |
## OpenAPI
````yaml POST /v1/users/search
openapi: 3.0.3
info:
title: Stytch API
description: The Stytch API provides endpoints for authentication and user management.
version: 2.1.1
contact:
name: Stytch Support
url: https://stytch.com/docs
email: support@stytch.com
servers:
- url: https://api.stytch.com
description: Production server
- url: https://test.stytch.com
description: Test server
security:
- basicAuth: []
paths:
/v1/users/search:
post:
tags:
- User
summary: Search
description: >-
**Warning**: This endpoint is not recommended for use in login flows.
Scaling issues may occur, as search performance may vary from ~150
milliseconds to 9 seconds depending on query complexity and rate limits
are set to 150 requests/minute.
Search for Users within your Stytch Project.
Use the `query` object to filter by different fields. See the
`query.operands.filter_value` documentation below for a list of
available filters.
### Export all User data
Submit an empty `query` in your Search Users request to return all of
your Stytch Project's Users.
[This Github
repository](https://github.com/stytchauth/stytch-node-export-users)
contains a utility that leverages the Search Users endpoint to export
all of your User data to a CSV or JSON file.
operationId: api_user_v1_Search
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/api_user_v1_SearchRequest'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/api_user_v1_SearchResponse'
'400':
description: Bad request
'401':
description: Unauthorized
content:
application/json:
example:
status_code: 401
request_id: request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141
error_type: unauthorized_credentials
error_message: Unauthorized credentials.
error_url: https://stytch.com/docs/api/errors/401
'429':
description: Too Many Requests
content:
application/json:
example:
status_code: 429
request_id: request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141
error_type: too_many_requests
error_message: Too many requests have been made.
error_url: https://stytch.com/docs/api/errors/429
'500':
description: Internal server error
content:
application/json:
example:
status_code: 500
request_id: request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141
error_type: internal_server_error
error_message: >-
Oops, something seems to have gone wrong, please reach out to
support@stytch.com to let us know what went wrong.
error_url: https://stytch.com/docs/api/errors/500
components:
schemas:
api_user_v1_SearchRequest:
type: object
properties:
cursor:
type: string
description: >-
The `cursor` field allows you to paginate through your results. Each
result array is limited to 1000 results. If your query returns more
than 1000 results, you will need to paginate the responses using the
`cursor`. If you receive a response that includes a non-null
`next_cursor` in the `results_metadata` object, repeat the search
call with the `next_cursor` value set to the `cursor` field to
retrieve the next page of results. Continue to make search calls
until the `next_cursor` in the response is null.
limit:
type: integer
format: int32
minimum: 0
description: >-
The number of search results to return per page. The default limit
is 100. A maximum of 1000 results can be returned by a single search
request. If the total size of your result set is greater than one
page size, you must paginate the response. See the `cursor` field.
query:
$ref: '#/components/schemas/api_user_v1_SearchUsersQuery'
description: >-
The optional query object contains the operator, i.e. `AND` or `OR`,
and the operands that will filter your results. Only an operator is
required. If you include no operands, no filtering will be applied.
If you include no query object, it will return all results with no
filtering applied.
description: Request type
api_user_v1_SearchResponse:
type: object
properties:
request_id:
type: string
description: >-
Globally unique UUID that is returned with every API call. This
value is important to log for debugging purposes; we may ask for
this value to help identify a specific API call when helping you
debug an issue.
results:
type: array
items:
$ref: '#/components/schemas/api_user_v1_User'
description: An array of results that match your search query.
results_metadata:
$ref: '#/components/schemas/api_user_v1_ResultsMetadata'
description: >-
The search `results_metadata` object contains metadata relevant to
your specific query like total and `next_cursor`.
status_code:
type: integer
format: int32
description: >-
The HTTP status code of the response. Stytch follows standard HTTP
response status code patterns, e.g. 2XX values equate to success,
3XX values are redirects, 4XX are client errors, and 5XX are server
errors.
required:
- request_id
- results
- results_metadata
- status_code
api_user_v1_SearchUsersQuery:
type: object
properties:
operator:
$ref: '#/components/schemas/api_user_v1_users_SearchUsersQueryOperator'
description: |-
The action to perform on the operands. The accepted values are:
`AND` – all the operand values provided must match.
`OR` – **[DEPRECATED]** the operator will return any matches to at least one of the operand values you supply. This parameter is retained for legacy use cases only and is no longer supported. We strongly recommend breaking down complex queries into multiple search queries instead.
operands:
type: array
items:
type: object
additionalProperties: true
description: >-
An array of operand objects that contains all of the filters and
values to apply to your search search query.
required:
- operator
- operands
api_user_v1_User:
type: object
properties:
user_id:
type: string
description: The unique ID of the affected User.
emails:
type: array
items:
$ref: '#/components/schemas/api_user_v1_Email'
description: An array of email objects for the User.
status:
type: string
description: >-
The status of the User. The possible values are `pending` and
`active`.
phone_numbers:
type: array
items:
$ref: '#/components/schemas/api_user_v1_PhoneNumber'
description: An array of phone number objects linked to the User.
webauthn_registrations:
type: array
items:
$ref: '#/components/schemas/api_user_v1_WebAuthnRegistration'
description: >-
An array that contains a list of all Passkey or WebAuthn
registrations for a given User in the Stytch API.
providers:
type: array
items:
$ref: '#/components/schemas/api_user_v1_OAuthProvider'
description: An array of OAuth `provider` objects linked to the User.
totps:
type: array
items:
$ref: '#/components/schemas/api_user_v1_TOTP'
description: >-
An array containing a list of all TOTP instances for a given User in
the Stytch API.
crypto_wallets:
type: array
items:
$ref: '#/components/schemas/api_user_v1_CryptoWallet'
description: >-
An array contains a list of all crypto wallets for a given User in
the Stytch API.
biometric_registrations:
type: array
items:
$ref: '#/components/schemas/api_user_v1_BiometricRegistration'
description: >-
An array that contains a list of all biometric registrations for a
given User in the Stytch API.
is_locked:
type: boolean
description: >-
Whether the User is temporarily locked due to too many failed
authentication attempts. See the [User Locking
Guide](https://stytch.com/docs/resources/platform/user-locks) for
more information.
roles:
type: array
items:
type: string
description: |-
Roles assigned to this User.
See the [RBAC guide](https://stytch.com/docs/guides/rbac/role-assignment) for more information about role assignment.
name:
$ref: '#/components/schemas/api_user_v1_Name'
description: The name of the User. Each field in the `name` object is optional.
created_at:
type: string
description: >-
The timestamp of the User's creation. Values conform to the RFC 3339
standard and are expressed in UTC, e.g. `2021-12-29T12:33:09Z`.
password:
$ref: '#/components/schemas/api_user_v1_Password'
description: The password object is returned for users with a password.
trusted_metadata:
type: object
additionalProperties: true
description: >-
The `trusted_metadata` field contains an arbitrary JSON object of
application-specific data. See the
[Metadata](https://stytch.com/docs/api/metadata) reference for
complete field behavior details.
untrusted_metadata:
type: object
additionalProperties: true
description: >-
The `untrusted_metadata` field contains an arbitrary JSON object of
application-specific data. Untrusted metadata can be edited by end
users directly via the SDK, and **cannot be used to store critical
information.** See the
[Metadata](https://stytch.com/docs/api/metadata) reference for
complete field behavior details.
external_id:
type: string
description: >-
An identifier that can be used in most API calls where a `member_id`
is expected. This is a string consisting of alphanumeric, `.`, `_`,
`-`, or `|` characters with a maximum length of 128 characters.
External IDs must be unique within the project.
lock_created_at:
type: string
description: >-
When the user lock was created, if there is one. Values conform to
the RFC 3339 standard and are expressed in UTC, e.g.
`2021-12-29T12:33:09Z`.
lock_expires_at:
type: string
description: >-
When the user lock expires, if there is one. Values conform to the
RFC 3339 standard and are expressed in UTC, e.g.
`2021-12-29T12:33:09Z`.
required:
- user_id
- emails
- status
- phone_numbers
- webauthn_registrations
- providers
- totps
- crypto_wallets
- biometric_registrations
- is_locked
- roles
api_user_v1_ResultsMetadata:
type: object
properties:
total:
type: integer
format: int32
description: >-
The total number of results returned by your search query. If totals
have been disabled for your Stytch Workspace to improve search
performance, the value will always be -1.
next_cursor:
type: string
description: >-
The `next_cursor` string is returned when your search result
contains more than one page of results. This value is passed into
your next search call in the `cursor` field.
required:
- total
api_user_v1_users_SearchUsersQueryOperator:
type: string
enum:
- OR
- AND
api_user_v1_Email:
type: object
properties:
email_id:
type: string
description: The unique ID of a specific email address.
email:
type: string
description: The email address.
verified:
type: boolean
description: >-
The verified boolean denotes whether or not this send method, e.g.
phone number, email address, etc., has been successfully
authenticated by the User.
required:
- email_id
- email
- verified
api_user_v1_PhoneNumber:
type: object
properties:
phone_id:
type: string
description: The unique ID for the phone number.
phone_number:
type: string
description: The phone number.
verified:
type: boolean
description: >-
The verified boolean denotes whether or not this send method, e.g.
phone number, email address, etc., has been successfully
authenticated by the User.
required:
- phone_id
- phone_number
- verified
api_user_v1_WebAuthnRegistration:
type: object
properties:
webauthn_registration_id:
type: string
description: The unique ID for the Passkey or WebAuthn registration.
domain:
type: string
description: >-
The `domain` on which Passkey or WebAuthn registration was started.
This will be the domain of your app.
user_agent:
type: string
description: The user agent of the User.
verified:
type: boolean
description: >-
The verified boolean denotes whether or not this send method, e.g.
phone number, email address, etc., has been successfully
authenticated by the User.
authenticator_type:
type: string
description: >-
The `authenticator_type` string displays the requested authenticator
type of the Passkey or WebAuthn device. The two valid types are
"platform" and "cross-platform". If no value is present, the Passkey
or WebAuthn device was created without an authenticator type
preference.
name:
type: string
description: The `name` of the Passkey or WebAuthn registration.
required:
- webauthn_registration_id
- domain
- user_agent
- verified
- authenticator_type
- name
api_user_v1_OAuthProvider:
type: object
properties:
provider_type:
type: string
description: >-
Denotes the OAuth identity provider that the user has authenticated
with, e.g. Google, Facebook, GitHub etc.
provider_subject:
type: string
description: >-
The unique identifier for the User within a given OAuth provider.
Also commonly called the "sub" or "Subject field" in OAuth
protocols.
profile_picture_url:
type: string
description: >-
If available, the `profile_picture_url` is a url of the User's
profile picture set in OAuth identity the provider that the User has
authenticated with, e.g. Facebook profile picture.
locale:
type: string
description: >-
If available, the `locale` is the User's locale set in the OAuth
identity provider that the user has authenticated with.
oauth_user_registration_id:
type: string
description: The unique ID for an OAuth registration.
required:
- provider_type
- provider_subject
- profile_picture_url
- locale
- oauth_user_registration_id
api_user_v1_TOTP:
type: object
properties:
totp_id:
type: string
description: The unique ID for a TOTP instance.
verified:
type: boolean
description: >-
The verified boolean denotes whether or not this send method, e.g.
phone number, email address, etc., has been successfully
authenticated by the User.
required:
- totp_id
- verified
api_user_v1_CryptoWallet:
type: object
properties:
crypto_wallet_id:
type: string
description: The unique ID for a crypto wallet
crypto_wallet_address:
type: string
description: The actual blockchain address of the User's crypto wallet.
crypto_wallet_type:
type: string
description: >-
The blockchain that the User's crypto wallet operates on, e.g.
Ethereum, Solana, etc.
verified:
type: boolean
description: >-
The verified boolean denotes whether or not this send method, e.g.
phone number, email address, etc., has been successfully
authenticated by the User.
required:
- crypto_wallet_id
- crypto_wallet_address
- crypto_wallet_type
- verified
api_user_v1_BiometricRegistration:
type: object
properties:
biometric_registration_id:
type: string
description: The unique ID for a biometric registration.
verified:
type: boolean
description: >-
The verified boolean denotes whether or not this send method, e.g.
phone number, email address, etc., has been successfully
authenticated by the User.
required:
- biometric_registration_id
- verified
api_user_v1_Name:
type: object
properties:
first_name:
type: string
description: The first name of the user.
middle_name:
type: string
description: The middle name(s) of the user.
last_name:
type: string
description: The last name of the user.
api_user_v1_Password:
type: object
properties:
password_id:
type: string
description: The unique ID of a specific password
requires_reset:
type: boolean
description: Indicates whether this password requires a password reset
required:
- password_id
- requires_reset
securitySchemes:
basicAuth:
type: http
scheme: basic
````