Better Auth · Module

auth.api.listUsers

Lists users through the Better Auth admin API, with optional search, pagination, sorting, and filtering. The server-side endpoint requires authenticated session cookies.

How it works

The admin plugin exposes listUsers through the server auth API. It accepts an optional query object for searching, pagination, sorting, and filtering, and requires session cookies in the server-side example.

Syntax

auth.api.listUsers({ query?, headers? })

Parameters

Name	Type	Description
`query`	`object`	Optional query options including searchValue, searchField, searchOperator, limit, offset, sortBy, sortDirection, filterField, filterValue, and filterOperator.
`headers`	`Headers`	Request headers containing the authenticated session cookies.

Returns

A user-list response containing users and pagination metadata such as total, limit, and offset.

Key points

The endpoint is intended for administrators to retrieve the user list.
Search defaults to the email field unless name is selected.
The search field accepts email or name.
Search behavior can use contains, starts_with, or ends_with.
Offset selects where the requested page begins.
Results can be ordered by a selected field and direction.
Filtering compares a chosen field against a supplied value.

Common mistakes

The server-side call must include session cookies through the headers option.
Without an explicit limit, the endpoint returns up to 100 users.

Example: List users with query options

const { users, total, limit, offset } = await auth.api.listUsers({
  query: {
    searchValue: "alice",
    searchField: "email",
    searchOperator: "contains",
    limit: 20,
    offset: 0,
    sortBy: "name",
    sortDirection: "asc",
    filterField: "email",
    filterValue: "@example.com",
    filterOperator: "contains",
  },
  headers: await headers(),
});

Calls the server API to retrieve matching users with pagination, sorting, and filtering.

When to use it

Paginated administration

Build an admin user-management table with pages of accounts.

User search

Locate accounts by email or display name.

Sorting and filtering

Order or narrow administrative results before rendering them.

Interview questions

QWhat capabilities does listUsers provide?

It is a server-side method exposed as auth.api.listUsers. The method can query users by search value, field, and operator, while also supporting pagination, sorting, and filtering.

Follow-up: How would you avoid requesting the entire result set? Supply limit and offset, then use the returned pagination metadata to request subsequent pages.

QWhich search and filter operators are supported?

The searchable field can be email or name. Search operators include contains, starts_with, and ends_with; filtering additionally supports operators such as eq.

Follow-up: How would you search names beginning with a prefix? Set searchField to name and searchOperator to starts_with.

QWhy are headers passed to the server call?

The server example passes headers from the current request because the endpoint requires session cookies. This lets Better Auth identify the authenticated session when the method is called.

Follow-up: What should a caller do if it invokes the method outside a request context? Ensure authenticated request headers are explicitly available and forwarded.

authClient.admin.listUsers
admin plugin
GET /admin/list-users

Source: Admin. Checked 2026-10-15.