`getUserList()`

Retrieves a list of users.


function getUserList(): (params: UserListParams) => Promise<PaginatedResourceResponse<User[]>>;

`UserListParams`

Name	Type	Description
`limit?`	`number`	The number of results to return. Must be an integer greater than zero and less than 501.
`offset?`	`number`	The number of results to skip.
`orderBy?`	`'created_at' \| 'updated_at' \| 'last_sign_in_at' \| 'last_active_at'`	The 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?`	`string`	The string to query by.
`userId?`	`string[]`	The user ID's to filter by.
`externalId?`	`string[]`	The external ID's to filter by.

`getUserList()` examples

`getUserList()` with no parameters

In this example, you can see that the returned PaginatedResourceResponse includes data, which is an array of User objects, and totalCount, which indicates the total number of users for the application.

While the response can return up to 10 data items, for the sake of brevity, only two are shown in this example response.


const response = await clerkClient.users.getUserList();
 
console.log(response);
/*
{
  data: [
    _User {
      id: 'user_2cAkrFJNEmOVuKQqLbKbj2glKcu',
      passwordEnabled: false,
      totpEnabled: false,
      backupCodeEnabled: false,
      twoFactorEnabled: false,
      banned: false,
      createdAt: 1707561967007,
      updatedAt: 1707561967095,
      imageUrl: 'https://img.clerk.com/eyJ0eXBlIjoicHJveHkiLCJzcmMiOiJodHRwczovL2ltYWdlcy5jbGVyay5kZXYvb2F1dGhfZ29vZ2xlL2ltZ18yY0Frckh3dWtza1NmYXhIajRLakNEbndJS2EifQ',
      hasImage: true,
      primaryEmailAddressId: 'idn_2cAkqw5hh4hN9AFYllNKSkJZZxu',
      primaryPhoneNumberId: null,
      primaryWeb3WalletId: null,
      lastSignInAt: 1707561967014,
      externalId: null,
      username: null,
      firstName: 'Vyacheslav',
      lastName: 'Ogai',
      publicMetadata: {},
      privateMetadata: {},
      unsafeMetadata: {},
      emailAddresses: [Array],
      phoneNumbers: [],
      web3Wallets: [],
      externalAccounts: [Array],
      lastActiveAt: 1707523200000,
      createOrganizationEnabled: true
    },
    _User {
      id: 'user_2cA1W52mI9k31aomHIZm5udQD6t',
      passwordEnabled: false,
      totpEnabled: false,
      backupCodeEnabled: false,
      twoFactorEnabled: false,
      banned: false,
      createdAt: 1707539597250,
      updatedAt: 1707539597331,
      imageUrl: 'https://img.clerk.com/eyJ0eXBlIjoicHJveHkiLCJzcmMiOiJodHRwczovL2ltYWdlcy5jbGVyay5kZXYvb2F1dGhfZ29vZ2xlL2ltZ18yY0ExVzRIM0o0Uk9EaGx6ZTcyTkhSRHc0TEwifQ',
      hasImage: true,
      primaryEmailAddressId: 'idn_2cA1W2G13Ke5SxfXeftcdZUbd1F',
      primaryPhoneNumberId: null,
      primaryWeb3WalletId: null,
      lastSignInAt: 1707539597260,
      externalId: null,
      username: null,
      firstName: 'Noah',
      lastName: 'Moscovici',
      publicMetadata: {},
      privateMetadata: {},
      unsafeMetadata: {},
      emailAddresses: [Array],
      phoneNumbers: [],
      web3Wallets: [],
      externalAccounts: [Array],
      lastActiveAt: 1707523200000,
      createOrganizationEnabled: true
    },
    ...
  ],
  totalCount: 500
}
*/

`getUserList({ orderBy, limit })`

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


const { data, totalCount } = 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 { data, totalCount } = 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 { data, totalCount } = await clerkClient.users.getUserList({
  query: 'test',
});

Backend API (BAPI) endpoint

This method in the SDK is a wrapper around the BAPI endpoint GET/users. See the BAPI reference(opens in a new tab) for more details.

Last updated on March 26, 2024

UserListParams

getUserList() examples

getUserList() with no parameters

getUserList({ orderBy, limit })

getUserList({ emailAddress, phoneNumber })

getUserList({ query })