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. Can be used for paginating the results together with offset. Defaults to 10.

  • Name
    offset?
    Type
    number
    Description

    Skip the first offset results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with limit. Defaults to 0.

  • Name
    orderBy?
    Type
    'created_at' | 'updated_at' | 'email_address' | 'web3wallet' | 'first_name' | 'last_name' | 'phone_number' | 'username' | 'last_active_at' | 'last_sign_in_at'
    Description

    Return users in a particular order. Prefix with a - to reverse the order. Prefix with a + to list in ascending order. Defaults to '-created_at'.

  • Name
    emailAddress?
    Type
    string[]
    Description

    Filters users with the specified email addresses. Accepts up to 100 email addresses. Any email addresses not found are ignored.

  • Name
    phoneNumber?
    Type
    string[]
    Description

    Filters users with the specified phone numbers. Accepts up to 100 phone numbers. Any phone numbers not found are ignored.

  • Name
    externalId?
    Type
    string[]
    Description

    Filters 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.

  • Name
    username?
    Type
    string[]
    Description

    Filters users with the specified usernames. Accepts up to 100 usernames. Any usernames not found are ignored.

  • Name
    web3Wallet?
    Type
    string[]
    Description

    Filters users with the specified web3 wallet addresses. Accepts up to 100 web3 wallet addresses. Any web3 wallet addressed not found are ignored.

  • Name
    userId?
    Type
    string[]
    Description

    Filters 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.

  • Name
    organizationId?
    Type
    string[]
    Description

    Filters 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.

  • Name
    query?
    Type
    string
    Description

    Filters 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.

  • Name
    last_active_at_since
    Type
    number
    Description

    Filters users that had session activity since the given date, with day precision. Providing a value with higher precision than day will result in an error. Example: use 1700690400000 to retrieve users that had session activity from 2023-11-23 until the current day. For example: 1700690400000.

Examples

Basic

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_123',
      passwordEnabled: false,
      totpEnabled: false,
      backupCodeEnabled: false,
      twoFactorEnabled: false,
      banned: false,
      createdAt: 1707561967007,
      updatedAt: 1707561967095,
      imageUrl: 'https://img.clerk.com/eyJ...',
      hasImage: true,
      primaryEmailAddressId: 'idn_123',
      primaryPhoneNumberId: null,
      primaryWeb3WalletId: null,
      lastSignInAt: 1707561967014,
      externalId: null,
      username: null,
      firstName: 'First',
      lastName: 'Test',
      publicMetadata: {},
      privateMetadata: {},
      unsafeMetadata: {},
      emailAddresses: [Array],
      phoneNumbers: [],
      web3Wallets: [],
      externalAccounts: [Array],
      lastActiveAt: 1707523200000,
      createOrganizationEnabled: true
    },
    _User {
      id: 'user_456',
      passwordEnabled: false,
      totpEnabled: false,
      backupCodeEnabled: false,
      twoFactorEnabled: false,
      banned: false,
      createdAt: 1707539597250,
      updatedAt: 1707539597331,
      imageUrl: 'https://img.clerk.com/eyJ...',
      hasImage: true,
      primaryEmailAddressId: 'idn_456',
      primaryPhoneNumberId: null,
      primaryWeb3WalletId: null,
      lastSignInAt: 1707539597260,
      externalId: null,
      username: null,
      firstName: 'Second',
      lastName: 'Test',
      publicMetadata: {},
      privateMetadata: {},
      unsafeMetadata: {},
      emailAddresses: [Array],
      phoneNumbers: [],
      web3Wallets: [],
      externalAccounts: [Array],
      lastActiveAt: 1707523200000,
      createOrganizationEnabled: true
    },
    ...
  ],
  totalCount: 500
}
*/

Limit the number of results

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,
});

Filter by email addresses and phone numbers

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 });

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.

// 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