Docs

getUserList()

Retrieves a list of users.

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

UserListParams

  • Name
    limit?
    Type
    number
    Description

    The number of results to return. Must be an integer greater than zero and less than 501.

  • Name
    offset?
    Type
    number
    Description

    The number of results to skip.

  • Name
    orderBy?
    Type
    'created_at' | 'updated_at' | 'last_sign_in_at' | 'last_active_at'
    Description

    The field to order by. Prefix with a - to reverse the order. Prefix with a + to list in ascending order.

  • Name
    emailAddress?
    Type
    string[]
    Description

    The email addresses to filter by.

  • Name
    phoneNumber?
    Type
    string[]
    Description

    The phone numbers to filter by.

  • Name
    username?
    Type
    string[]
    Description

    The usernames to filter by.

  • Name
    web3Wallet?
    Type
    string[]
    Description

    The web3Wallets to filter by.

  • Name
    query?
    Type
    string
    Description

    The string to query by.

  • Name
    userId?
    Type
    string[]
    Description

    The user ID's to filter by.

  • Name
    externalId?
    Type
    string[]
    Description

    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 for more details.

Feedback

What did you think of this content?
Edit this page on GitHub