Clerk API (unofficial showcase)
GET/users

List all users

Returns a list of all users. The users are returned sorted by creation date, with the newest users appearing first.

To walk more than a few pages, paginate with starting_after rather than offset. A cursor page costs the same no matter how far into the list it sits, while a large offset has to walk and discard every row before it, so it gets progressively slower and eventually times out. Cursor pagination requires the created_at ordering, which is the default.

26 parameters
email_addressarray<string>optional
Returns users with the specified email addresses. Accepts up to 100 email addresses. Any email addresses not found are ignored.
phone_numberarray<string>optional
Returns users with the specified phone numbers. Accepts up to 100 phone numbers. Any phone numbers not found are ignored.
external_idarray<string>optional
Returns users with the specified external IDs. For each external ID, the `+` and `-` can be prepended to the ID, which denote whether the respective external ID should be included or excluded from the result set. Accepts up to 100 external IDs. Any external IDs not found are ignored.
usernamearray<string>optional
Returns users with the specified usernames. Accepts up to 100 usernames. Any usernames not found are ignored.
web3_walletarray<string>optional
Returns users with the specified web3 wallet addresses. Accepts up to 100 web3 wallet addresses. Any web3 wallet addresses not found are ignored.
user_idarray<string>optional
Returns users with the user IDs specified. For each user ID, the `+` and `-` can be prepended to the ID, which denote whether the respective user ID should be included or excluded from the result set. Accepts up to 100 user IDs. Any user IDs not found are ignored.
organization_idarray<string>optional
Returns users that have memberships to the given organizations. For each organization ID, the `+` and `-` can be prepended to the ID, which denote whether the respective organization should be included or excluded from the result set. Accepts up to 100 organization IDs.
querystringoptional
Returns users that match the given query. For possible matches, we check the email addresses, phone numbers, usernames, web3 wallets, user IDs, first and last names. The query value doesn't need to match the exact value you are looking for, it is capable of partial matches as well.
email_address_querystringoptional
Returns users with emails that match the given query, via case-insensitive partial match. For example, `email_address_query=ello` will match a user with the email `HELLO@example.com`.
phone_number_querystringoptional
Returns users with phone numbers that match the given query, via case-insensitive partial match. For example, `phone_number_query=555` will match a user with the phone number `+1555xxxxxxx`.
username_querystringoptional
Returns users with usernames that match the given query, via case-insensitive partial match. For example, `username_query=CoolUser` will match a user with the username `SomeCoolUser`.
name_querystringoptional
Returns users with names that match the given query, via case-insensitive partial match.
bannedbooleanoptional
Returns users which are either banned (`banned=true`) or not banned (`banned=false`).
last_active_at_beforeintegeroptional
Returns users whose last session activity was before the given date (with millisecond precision). Example: use 1700690400000 to retrieve users whose last session activity was before 2023-11-23.
last_active_at_afterintegeroptional
Returns users whose last session activity was after the given date (with millisecond precision). Example: use 1700690400000 to retrieve users whose last session activity was after 2023-11-23.
last_active_at_sinceintegeroptional
Returns users that had session activity since the given date. Example: use 1700690400000 to retrieve users that had session activity from 2023-11-23 until the current day. Deprecated in favor of `last_active_at_after`.
created_at_beforeintegeroptional
Returns users who have been created before the given date (with millisecond precision). Example: use 1730160000000 to retrieve users who have been created before 2024-10-29.
created_at_afterintegeroptional
Returns users who have been created after the given date (with millisecond precision). Example: use 1730160000000 to retrieve users who have been created after 2024-10-29.
last_sign_in_at_beforeintegeroptional
Returns users whose last sign-in was before the given date (with millisecond precision). Example: use 1700690400000 to retrieve users whose last sign-in was before 2023-11-23.
last_sign_in_at_afterintegeroptional
Returns users whose last sign-in was after the given date (with millisecond precision). Example: use 1700690400000 to retrieve users whose last sign-in was after 2023-11-23.
providerstringoptional
Returns users with external accounts for the specified OAuth provider. Must be used in combination with the `provider_user_id` parameter. For example, use `provider=oauth_google&provider_user_id=12345` to retrieve a user with Google provider user ID 12345.
provider_user_idarray<string>optional
Returns users with the specified provider user IDs for a specific provider. Must be used in combination with the `provider` parameter. For example, use `provider=oauth_google&provider_user_id=12345` to retrieve a user with Google provider user ID 12345. Accepts up to 100 provider user IDs. Any provider user IDs not found are ignored.
limitintegeroptional
Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`.
Default:10
offsetintegeroptional
Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.
Default:0
starting_afterstringoptional
A cursor for pagination: the `id` of the last user on the previous page. Returns the users that follow it. **Requires ordering by `created_at`** — that is, `order_by` omitted, or set to `created_at`, `+created_at` or `-created_at`. Any other `order_by` value is rejected with a 422: the other orderings sort by a value that is neither unique per user nor immutable, so a cursor over them would skip or repeat users. Cannot be combined with a non-zero `offset`, which is also a 422. Keep every other parameter identical across requests, and stop when a page returns fewer than `limit` users.
order_bystringoptional
Allows to return users in a particular order. At the moment, you can order the returned users by their `created_at`,`updated_at`,`email_address`,`web3wallet`,`first_name`,`last_name`,`phone_number`,`username`,`last_active_at`,`last_sign_in_at`. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. For example, if you want users to be returned in descending order according to their `created_at` property, you can use `-created_at`. If you don't use `+` or `-`, then `+` is implied. We only support one `order_by` parameter, and if multiple `order_by` parameters are provided, we will only keep the first one. For example, if you pass `order_by=username&order_by=created_at`, we will consider only the first `order_by` parameter, which is `username`. The `created_at` parameter will be ignored in this case. Only the `created_at` orderings can be combined with `starting_after` cursor pagination; see that parameter.
Default:-created_at

4 status codes
200Success
idstringrequired
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:user
external_idstringrequired
primary_email_address_idstringrequired
primary_phone_number_idstringrequired
primary_web3_wallet_idstringrequired
usernamestringrequired
first_namestringrequired
last_namestringrequired
localestringoptional
timezonestringoptional
profile_image_urlstringdeprecatedoptional
image_urlstringoptional
has_imagebooleanrequired
public_metadataobjectrequired
private_metadataobjectoptional
unsafe_metadataobjectoptional
email_addressesarray<object>required
phone_numbersarray<object>required
web3_walletsarray<object>required
passkeysarray<object>required
password_enabledbooleanrequired
two_factor_enabledbooleanrequired
totp_enabledbooleanrequired
backup_code_enabledbooleanrequired
mfa_enabled_atintegerrequired
Unix timestamp of when MFA was last enabled for this user. It should be noted that this field is not nullified if MFA is disabled.
mfa_disabled_atintegerrequired
Unix timestamp of when MFA was last disabled for this user. It should be noted that this field is not nullified if MFA is enabled again.
password_last_updated_atintegeroptional
Unix timestamp of when the user's password was last updated.
external_accountsarray<object>required
saml_accountsarray<object>required
enterprise_accountsarray<object>required
organization_membershipsarray<object>optional
last_sign_in_atintegerrequired
Unix timestamp of last sign-in.
bannedbooleanrequired
Flag to denote whether user is banned or not.
lockedbooleanrequired
Flag to denote whether user is currently locked, i.e. restricted from signing in or not.
deprovisionedbooleanoptional
Flag to denote whether user has been deprovisioned and is restricted from signing in.
lockout_expires_in_secondsintegerrequired
The number of seconds remaining until the lockout period expires for a locked user. A null value for a locked user indicates that lockout never expires.
verification_attempts_remainingintegerrequired
The number of verification attempts remaining until the user is locked. Null if account lockout is not enabled. Note: if a user is locked explicitly via the Backend API, they may still have verification attempts remaining.
updated_atintegerrequired
Unix timestamp of last update.
created_atintegerrequired
Unix timestamp of creation.
delete_self_enabledbooleanrequired
If enabled, user can delete themselves via FAPI.
create_organization_enabledbooleanrequired
If enabled, user can create organizations via FAPI.
create_organizations_limitintegeroptional
The maximum number of organizations the user can create. 0 means unlimited.
last_active_atintegerrequired
Unix timestamp of the latest session activity, with day precision.
legal_accepted_atintegerrequired
Unix timestamp of when the user accepted the legal requirements.
bypass_client_trustbooleanoptional
When set to `true`, the user will bypass Device Trust checks during sign-in.
Default:false
directoriesarray<object>optional
All loaded directory links. Omitted when links were not loaded; an empty array means the user has no directory links.
directoryobjectdeprecatedoptional
The most recently updated directory link. Use directories for all links.
scimobjectdeprecatedoptional
Alias of directory. Use directories for all links.
400Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
401Authentication invalid
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Invalid request parameters
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned: Request was not successful. A 401 is returned: Authentication invalid. A 422 is returned: Invalid request parameters.