Skip to main content

getUserList()

Retrieves the list of users in your instance. By default, the list is returned in descending order by creation date (newest first).

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 in your instance.

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

UserListParams

  • Name
    createdAtAfter?
    Type
    number
    Description

    Filters users who were created after the given date (with millisecond precision).

  • Name
    createdAtBefore?
    Type
    number
    Description

    Filters users who were created before the given date (with millisecond precision).

  • Name
    emailAddress?
    Type
    string[]
    Description

    Filters users with the specified email addresses. Accepts up to 100 email addresses.

  • Name
    externalId?
    Type
    string[]
    Description

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

  • Name
    last_active_at_since?
    Type
    number
    Description

    Deprecated. Use lastActiveAtAfter instead. This parameter will be removed in a future version.

  • Name
    lastActiveAtAfter?
    Type
    number
    Description

    Filters users who were last active after the given date (with millisecond precision).

  • Name
    lastActiveAtBefore?
    Type
    number
    Description

    Filters users who were last active before the given date (with millisecond precision).

  • Name
    lastSignInAtAfter?
    Type
    number
    Description

    Filters users who were last signed in after the given date (with millisecond precision).

  • Name
    lastSignInAtBefore?
    Type
    number
    Description

    Filters users who were last signed in before the given date (with millisecond precision).

  • Name
    limit?
    Type
    number
    Description

    Maximum number of items returned per request. 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 items 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
    WithSign<"created_at" | "updated_at" | "email_address" | "web3wallet" | "first_name" | "last_name" | "phone_number" | "username" | "last_active_at" | "last_sign_in_at">
    Description

    Filters users in a particular order. Prefix a value with + to sort in ascending order, or - to sort in descending order. Defaults to -created_at.

  • Name
    organizationId?
    Type
    string[]
    Description

    Filters users who are members of the specified Organizations. Accepts up to 100 Organization IDs.

  • Name
    phoneNumber?
    Type
    string[]
    Description

    Filters users with the specified phone numbers. Accepts up to 100 phone numbers.

  • Name
    query?
    Type
    string
    Description

    Filters users matching the given query across email addresses, phone numbers, usernames, Web3 wallet addresses, user IDs, first names, and last names. Partial matches supported.

  • Name
    userId?
    Type
    string[]
    Description

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

  • Name
    username?
    Type
    string[]
    Description

    Filters users with the specified usernames. Accepts up to 100 usernames.

  • Name
    web3Wallet?
    Type
    string[]
    Description

    Filters users with the specified Web3 wallet addresses. Accepts up to 100 Web3 wallet addresses.

Usage

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.

Basic

const response = await clerkClient.users.getUserList()

Limit the number of results

Gets a list of users, ordered and limited to the specified number of results.

const { data, totalCount } = await clerkClient.users.getUserList({
  orderBy: '-created_at',
  limit: 10,
})

Filter by email addresses and phone numbers

Gets a list of users 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

Gets a list of users who 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