Skip to Content
Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.com

getUserList()

Retrieves a list of users.

const users = await clerkClient.users.getUserList();

UserListParams

NameTypeDescription
limit?numberThe number of results to return. Must be an integer greater than zero and less than 500.
offset?numberThe number of results to skip.
orderBy?created_at | updated_atThe field to order by. Prefix with a - to reverse the order. Prefix with a + to list in ascending order.
emailAddress?string[]The email addresses to filter by.
phoneNumber?string[]The phone numbers to filter by.
username?string[]The usernames to filter by.
web3Wallet?string[]The web3Wallets to filter by.
query?stringThe string to query by.
userId?string[]The user ID's to filter by.
externalId?string[]The external ID's to filter by.

Examples

getUserList({ orderBy, limit })

Retrieves user list that is ordered and filtered by the number of results.

const sessions = await clerkClient.users.getUserList({ orderBy: '-created_at', limit: 10, });

getUserList({ emailAddress, phoneNumber })

Retrieves user list that is filtered by the given email addresses and phone numbers.

const emailAddress = ['email1@clerk.dev', 'email2@clerk.dev']; const phoneNumber = ['+12025550108']; // If these filters are included, the response will contain only users that own any of these emails and/or phone numbers. const sessions = await clerkClient.users.getUserList({ emailAddress, phoneNumber });

getUserList({ query })

To do a broader match through a list of fields, you can use the query parameter which partially matches the fields: userId, emailAddress, phoneNumber, username, web3Wallet, firstName and lastName.

// Matches users with the string `test` matched in multiple user attributes. const usersMatchingTest = await clerkClient.users.getUserList({ query: 'test', });

Last updated on November 22, 2023

What did you think of this content?

Clerk © 2024