Display an application’s users
Administrative user directory
Clerk · Module
users.getUserList
Lists users in the current Clerk instance with optional filters, ordering, and pagination. The response contains matching User objects plus the instance-wide total count.
How it works
Call this server-side Clerk client method with optional filters, sorting, and pagination settings. It returns a paginated response whose data array contains User objects and whose totalCount reports the instance-wide user count.
Syntax
function getUserList(params: UserListParams): Promise<PaginatedResourceResponse<User[]>>Parameters
| Name | Type | Description |
|---|---|---|
params | UserListParams | Optional filtering, ordering, and pagination settings, including emailAddress, createdAtAfter, createdAtBefore, lastSignInAtAfter, lastSignInAtBefore, limit, offset, and orderBy. |
Returns
Promise<PaginatedResourceResponse<User[]>>
Key points
- The method lists users belonging to the current Clerk instance.
- Without an explicit orderBy value, newly created users appear first.
- The result is paginated and places the returned User objects in data.
- totalCount reports how many users exist in the instance.
- The limit parameter caps how many users one request returns.
- The emailAddress parameter selects users matching supplied email addresses.
- createdAtAfter excludes users created at or before the supplied millisecond timestamp.
Common mistakes
- The limit must be between 1 and 500; values outside that range are invalid.
- The emailAddress filter cannot contain more than 100 addresses.
- Use offset together with limit when paginating results.
Example: List the newest users
import { clerkClient } from '@clerk/nextjs/server'
const client = await clerkClient()
const { data, totalCount } = await client.users.getUserList({
orderBy: '-created_at',
limit: 10,
})
console.log({ users: data, totalCount })Creates the server-side Clerk client, retrieves up to 10 newest users, and logs the returned users and total count.
When to use it
Find users by email address
Moderation or support tooling
Query users by creation or sign-in time
Reporting and lifecycle analysis
Interview questions
QWhat does getUserList return?
It returns a Promise resolving to a PaginatedResourceResponse<User[]>. The response exposes the matching users through data and the instance user count through totalCount.
Follow-up: How would you retrieve the newest 25 users? Pass orderBy: '-created_at' and limit: 25 in the parameter object.
QWhat ordering does the method use by default?
With no ordering argument, users are returned newest first by creation date. The documented default ordering is -created_at.
Follow-up: How would you request oldest-first ordering? Use orderBy: '+created_at'.
QHow do you filter and paginate the user list?
Use filters such as emailAddress, createdAtAfter, createdAtBefore, lastSignInAtAfter, and lastSignInAtBefore in UserListParams. limit controls page size, while offset works with limit for pagination.
Follow-up: How can you constrain a query to a sign-in interval? Supply the after and before Unix timestamps through lastSignInAtAfter and lastSignInAtBefore.
Related
UserListParamsPaginatedResourceResponseUserclerkClientGET /users