> ## Documentation Index
> Fetch the complete documentation index at: https://docs.collab-kit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Users

> List all users in a room with pagination and search.

Retrieve a paginated list of users in a specific room.

## Endpoint

```
GET /v1/accounts/:accountId/users
```

## Authentication

**Bearer token** required. This endpoint accepts either an account API token or a user JWT. The client SDK uses this endpoint internally for `client.users.list(...)`.

## Query Parameters

<ParamField query="roomId" type="string" required>
  The room ID to list users for.
</ParamField>

<ParamField query="limit" type="number" default="50">
  Number of users to return. Maximum `100`.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of users to skip for pagination.
</ParamField>

<ParamField query="search" type="string">
  Case-insensitive partial match on user name or ID.
</ParamField>

## Response

<ResponseField name="users" type="CollabKitUser[]">
  Array of user objects. See [`CollabKitUser`](/types/core#collabkituser).
</ResponseField>

<ResponseField name="total" type="number">
  Total number of users matching the query.
</ResponseField>

<ResponseField name="limit" type="number">
  The limit used in this request.
</ResponseField>

<ResponseField name="offset" type="number">
  The offset used in this request.
</ResponseField>

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.collab-kit.com/v1/accounts/${ACCOUNT_ID}/users?roomId=c3003c93-60cf-4184-b85f-20be14d26dac&limit=10" \
    -H "Authorization: Bearer ${TOKEN}"
  ```

  ```typescript JavaScript theme={null}
  const res = await fetch(
    `https://api.collab-kit.com/v1/accounts/${accountId}/users?roomId=${roomId}&limit=10`,
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  const { data } = await res.json();
  console.log(data.users, data.total);

  // SDK equivalent. This auto-populates client.users.all and excludes self.
  const page = await client.users.list({ pageSize: 100, offset: 0 });
  ```
</CodeGroup>

```json Response theme={null}
{
  "type": "response",
  "success": true,
  "description": "Users retrieved",
  "data": {
    "users": [
      {
        "id": "f47ac10b-58cc-4372-...",
        "room_id": "c3003c93-...",
        "name": "Alice",
        "profile_picture": "https://example.com/alice.png",
        "custom_id": "alice-001",
        "status": "online",
        "created_at": "2026-05-29T10:05:00.000Z",
        "joined_at": "2026-05-29T10:06:00.000Z",
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
      }
    ],
    "total": 5,
    "limit": 10,
    "offset": 0
  },
  "error": null
}
```