# getUserList() Retrieves a list of users. Returns a [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response.md) object with a `data` property that contains an array of [`User`](https://clerk.com/docs/reference/backend/types/backend-user.md) objects, and a `totalCount` property that indicates the total number of users for the application. ```tsx function getUserList(): (params: UserListParams) => Promise> ``` ## `UserListParams` | Name | Type | Description | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | createdAtAfter? | number | Filters users who were created after the given timestamp (in milliseconds since epoch). | | createdAtBefore? | number | Filters users who were created before the given timestamp (in milliseconds since epoch). | | emailAddress? | string[] | Filters users with the specified email addresses. Accepts up to 100 email addresses. Prefix with - for descending, + for ascending. | | externalId? | string[] | Filters users with the specified external IDs. Accepts up to 100 external IDs. | | firstName? | string[] | Filters users with the specified first names. Accepts up to 100 first names. | | lastActiveAtAfter? | number | Filters users who have been active after the given timestamp (in milliseconds since epoch, day precision). | | lastActiveAtBefore? | number | Filters users who were last active before the given timestamp (in milliseconds since epoch, day precision). | | lastName? | string[] | Filters users with the specified last names. Accepts up to 100 last names. | | lastSignInAtAfter? | number | Filters users who signed in after the given timestamp (in milliseconds since epoch). | | lastSignInAtBefore? | number | Filters users who signed in before the given timestamp (in milliseconds since epoch). | | last\_active\_at\_since? | number | (Deprecated) Use lastActiveAtAfter instead. Filters users that had session activity since the given date (day precision, in ms since epoch). | | limit? | number | The number of results to return. Must be an integer greater than zero and less than 501. Used for pagination with offset. Defaults to 10. | | offset? | number | Skip the first offset results for pagination. Must be integer >= 0. Used alongside limit. Defaults to 0. | | orderBy? | 'created\_at' | 'updated\_at' | 'email\_address' | 'web3wallet' | 'first\_name' | 'last\_name' | 'phone\_number' | 'username' | 'last\_active\_at' | 'last\_sign\_in\_at' (optionally prefixed with +/-) | Return users in a particular order. Prefix with - for descending, + for ascending. Defaults to '-created\_at'. | | organizationId? | string[] | Filters users with memberships to the given organization IDs. Prefix with - for descending, + for ascending. Up to 100 accepted. | | phoneNumber? | string[] | Filters users with the specified phone numbers. Accepts up to 100 phone numbers. Prefix with - for descending, + for ascending. | | query? | string | Filters for users matching across email, phone, username, wallet address, user ID, first name, last name. Partial matches supported. | | userId? | string[] | Filters users with the user IDs specified. Accepts up to 100 user IDs. | | username? | string[] | Filters users by username. Up to 100. | | web3Wallet? | string[] | Filters users with the given Web3 wallet addresses. Accepts up to 100 Web3 wallet addresses. Prefix with - for descending, + for ascending. | ## Examples ### Basic > Using `clerkClient` varies based on the SDK you're using. Refer to the [overview](https://clerk.com/docs/reference/backend/overview.md) for usage details, including guidance on [how to access the `userId` and other properties](https://clerk.com/docs/reference/backend/overview.md#example-get-the-user-id-and-other-properties). ```tsx const response = await clerkClient.users.getUserList() ``` ### Limit the number of results Retrieves user list that is ordered and filtered by the number of results. ```tsx const { data, totalCount } = await clerkClient.users.getUserList({ orderBy: '-created_at', limit: 10, }) ``` ### Filter by email addresses and phone numbers Retrieves user list that is filtered by the given email addresses and phone numbers. ```tsx 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 { data, totalCount } = await clerkClient.users.getUserList({ emailAddress, phoneNumber }) ``` ### Filter by 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`. ```tsx // Matches users with the string `test` matched in multiple user attributes. const { data, totalCount } = await clerkClient.users.getUserList({ query: 'test', }) ``` ### Filter by last sign-in date Retrieve users that signed in within a specific time range. ```tsx // Matches users that signed in between the given Unix timestamps. const { data, totalCount } = await clerkClient.users.getUserList({ lastSignInAtAfter: 1700690400000, lastSignInAtBefore: 1700690400010, }) ``` ## Backend API (BAPI) endpoint This method in the SDK is a wrapper around the BAPI endpoint `GET/users`. See the [BAPI reference](https://clerk.com/docs/reference/backend-api/tag/users/GET/users){{ target: '_blank' }} for more information. --- ## Sitemap [Overview of all docs pages](https://clerk.com/docs/llms.txt)