Skip to main content
Docs

getUserList()

Retrieves a list of users. Returns a PaginatedResourceResponse object with a data property that contains an array of User objects, and a totalCount property that indicates the total number of users for the application.

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

UserListParams

  • Name
    createdAtAfter?
    Type
    number
    Description

    Filters users who were created after the given timestamp (in milliseconds since epoch).

  • Name
    createdAtBefore?
    Type
    number
    Description

    Filters users who were created before the given timestamp (in milliseconds since epoch).

  • Name
    emailAddress?
    Type
    string[]
    Description

    Filters users with the specified email addresses. Accepts up to 100 email addresses. Prefix with - for descending, + for ascending.

  • Name
    externalId?
    Type
    string[]
    Description

    Filters users with the specified external IDs. Accepts up to 100 external IDs.

  • Name
    firstName?
    Type
    string[]
    Description

    Filters users with the specified first names. Accepts up to 100 first names.

  • Name
    lastActiveAtAfter?
    Type
    number
    Description

    Filters users who have been active after the given timestamp (in milliseconds since epoch, day precision).

  • Name
    lastActiveAtBefore?
    Type
    number
    Description

    Filters users who were last active before the given timestamp (in milliseconds since epoch, day precision).

  • Name
    lastName?
    Type
    string[]
    Description

    Filters users with the specified last names. Accepts up to 100 last names.

  • Name
    lastSignInAtAfter?
    Type
    number
    Description

    Filters users who signed in after the given timestamp (in milliseconds since epoch).

  • Name
    lastSignInAtBefore?
    Type
    number
    Description

    Filters users who signed in before the given timestamp (in milliseconds since epoch).

  • Name
    last_active_at_since?
    Type
    number
    Description

    (Deprecated) Use lastActiveAtAfter instead. Filters users that had session activity since the given date (day precision, in ms since epoch).

  • Name
    limit?
    Type
    number
    Description

    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.

  • Name
    offset?
    Type
    number
    Description

    Skip the first offset results for pagination. Must be integer >= 0. Used alongside 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' (optionally prefixed with +/-)
    Description

    Return users in a particular order. Prefix with - for descending, + for ascending. Defaults to '-created_at'.

  • Name
    organizationId?
    Type
    string[]
    Description

    Filters users with memberships to the given organization IDs. Prefix with - for descending, + for ascending. Up to 100 accepted.

  • Name
    phoneNumber?
    Type
    string[]
    Description

    Filters users with the specified phone numbers. Accepts up to 100 phone numbers. Prefix with - for descending, + for ascending.

  • Name
    query?
    Type
    string
    Description

    Filters for users matching across email, phone, username, wallet address, user ID, first name, last name. Partial matches supported.

  • Name
    userId?
    Type
    string[]
    Description

    Filters users with the user IDs specified. Accepts up to 100 user IDs.

  • Name
    username?
    Type
    string[]
    Description

    Filters users by username. Up to 100.

  • Name
    web3Wallet?
    Type
    string[]
    Description

    Filters users with the given Web3 wallet addresses. Accepts up to 100 Web3 wallet addresses. Prefix with - for descending, + for ascending.

Examples

Basic

Note

Using clerkClient varies based on the SDK you're using. Refer to the overview for usage details, including guidance on how to access the userId and other properties.

const response = await clerkClient.users.getUserList()

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

Filter by last sign-in date

Retrieve users that signed in within a specific time range.

// 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 for more information.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub