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

# List Users

Retrieves a paginated list of users with their group memberships and total count.

## Authentication

Requires admin authentication.

## Query Parameters

<ParamField query="query" type="string">
  Search query to filter users by name or email
</ParamField>

<ParamField query="order_by" type="string">
  Field to order results by. Options: `name`, `email`, `created_at`, `last_active_at`, `updated_at`, `role`, or `group_id:{group_id}` for custom group ordering
</ParamField>

<ParamField query="direction" type="string">
  Sort direction. Options: `asc` or `desc`
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination (minimum: 1)
</ParamField>

## Response

<ResponseField name="users" type="array">
  Array of user objects with group IDs

  <Expandable title="User Object">
    <ResponseField name="id" type="string">
      Unique user identifier
    </ResponseField>

    <ResponseField name="email" type="string">
      User email address
    </ResponseField>

    <ResponseField name="username" type="string" optional>
      Username (optional)
    </ResponseField>

    <ResponseField name="role" type="string">
      User role: `admin`, `user`, or `pending`
    </ResponseField>

    <ResponseField name="name" type="string">
      User display name
    </ResponseField>

    <ResponseField name="profile_image_url" type="string" optional>
      URL to user's profile image
    </ResponseField>

    <ResponseField name="profile_banner_image_url" type="string" optional>
      URL to user's profile banner image
    </ResponseField>

    <ResponseField name="bio" type="string" optional>
      User biography
    </ResponseField>

    <ResponseField name="gender" type="string" optional>
      User gender
    </ResponseField>

    <ResponseField name="date_of_birth" type="string" optional>
      User date of birth (ISO date format)
    </ResponseField>

    <ResponseField name="timezone" type="string" optional>
      User timezone
    </ResponseField>

    <ResponseField name="presence_state" type="string" optional>
      User presence state
    </ResponseField>

    <ResponseField name="status_emoji" type="string" optional>
      Status emoji
    </ResponseField>

    <ResponseField name="status_message" type="string" optional>
      Status message text
    </ResponseField>

    <ResponseField name="status_expires_at" type="integer" optional>
      Unix timestamp when status expires
    </ResponseField>

    <ResponseField name="info" type="object" optional>
      Additional user information (JSON)
    </ResponseField>

    <ResponseField name="settings" type="object" optional>
      User settings object

      <Expandable title="Settings Object">
        <ResponseField name="ui" type="object" default="{}">
          UI-specific settings
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="oauth" type="object" optional>
      OAuth authentication data
    </ResponseField>

    <ResponseField name="scim" type="object" optional>
      SCIM provisioning data
    </ResponseField>

    <ResponseField name="last_active_at" type="integer">
      Unix timestamp of last activity
    </ResponseField>

    <ResponseField name="updated_at" type="integer">
      Unix timestamp of last update
    </ResponseField>

    <ResponseField name="created_at" type="integer">
      Unix timestamp of creation
    </ResponseField>

    <ResponseField name="group_ids" type="array">
      Array of group IDs the user belongs to
    </ResponseField>
  </Expandable>
</ResponseField>

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

## Example Request

```bash theme={null}
curl -X GET "https://your-domain.com/api/users?page=1&order_by=name&direction=asc" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Example Response

```json theme={null}
{
  "users": [
    {
      "id": "user-123",
      "email": "user@example.com",
      "username": "johndoe",
      "role": "user",
      "name": "John Doe",
      "profile_image_url": "/api/v1/users/user-123/profile/image",
      "bio": "Software developer",
      "last_active_at": 1709424000,
      "updated_at": 1709424000,
      "created_at": 1709337600,
      "group_ids": ["group-1", "group-2"]
    }
  ],
  "total": 1
}
```

## Notes

* Returns 30 users per page
* Users are returned with their associated group IDs
* Profile image URLs default to `/api/v1/users/{id}/profile/image` if not set