listUsers()

Retrieves a list of users. Returns a PaginatedResponse<User> object with data, total, limit, and offset fields for offset-based pagination.

Usage

The following example shows a basic usage of the backend client from @wacht/nextjs/server.

import { wachtClient } from '@wacht/nextjs/server';export async function listRecentUsers() {  const client = await wachtClient();  return client.users.listUsers({ limit: 20, offset: 0 });}

Signature

function listUsers(  options?: ListUsersOptions,): Promise<PaginatedResponse<User>>

ListUsersOptions

›

limit?: number | undefined;

Maximum number of users to return for this page. When omitted, the backend keeps its default page size.

›

offset?: number | undefined;

Number of users to skip before returning results. Use it together with `limit` for offset-based pagination.

›

sort_key?: "created_at" | "username" | "email" | "phone_number" | undefined;

Sort field used by the backend user list query.

›

sort_order?: "asc" | "desc" | undefined;

Sort direction for the selected `sort_key`.

›

search?: string | undefined;

Search term forwarded to the backend user list query.

Return value

›

data?: User[] | undefined;

The users returned for the current page.

›

id?: string | undefined;

Stable user identifier.

›

created_at?: string | undefined;

Creation timestamp.

›

updated_at?: string | undefined;

Last update timestamp.

›

first_name?: string | undefined;

User first name.

›

last_name?: string | undefined;

User last name.

›

username?: string | undefined;

Optional username.

›

profile_picture_url?: string | undefined;

Resolved profile picture URL.

›

primary_email_address?: string | undefined;

Primary email address string when one exists.

›

primary_phone_number?: string | undefined;

Primary phone number string when one exists.

›

total?: number | undefined;

Total number of users matching the current query.

›

limit?: number | undefined;

The effective page size reflected by the backend when present.

›

offset?: number | undefined;

The effective offset reflected by the backend when present.

Behavior

Returns a backend-scoped list response for this resource.
Use pagination and filters from this method to build admin list views.

Examples

Basic

import { wachtClient } from '@wacht/nextjs/server';export async function listUsers() {  const client = await wachtClient();  const response = await client.users.listUsers();  return response;}

Limit the number of results

import { wachtClient } from '@wacht/nextjs/server';export async function listFirstTenUsers() {  const client = await wachtClient();  const { data, total, limit, offset } = await client.users.listUsers({    limit: 10,    offset: 0,  });  return { data, total, limit, offset };}

Search users

import { wachtClient } from '@wacht/nextjs/server';export async function searchUsers(search: string) {  const client = await wachtClient();  return client.users.listUsers({    search,    limit: 20,  });}

Sort by username

import { wachtClient } from '@wacht/nextjs/server';export async function listUsersByUsername() {  const client = await wachtClient();  return client.users.listUsers({    sort_key: 'username',    sort_order: 'asc',    limit: 25,  });}

Iterate through several pages

import { wachtClient } from '@wacht/nextjs/server';export async function exportUsers() {  const client = await wachtClient();  const allUsers = [];  let offset = 0;  while (true) {    const page = await client.users.listUsers({      limit: 100,      offset,    });    allUsers.push(...page.data);    offset += page.data.length;    if (offset >= page.total || page.data.length === 0) {      break;    }  }  return allUsers;}

Read only the user ids from the current page

import { wachtClient } from '@wacht/nextjs/server';export async function listUserIds() {  const client = await wachtClient();  const { data } = await client.users.listUsers({ limit: 25 });  return data.map((user) => user.id);}