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

# List Users

> Retrieve the users in your organization, with pagination and optional filters for role, active status, and group membership.

## Endpoint

```
GET /users
```

## Authentication

This endpoint requires authentication via API key. Include your API key in the `X-API-Key` header:

```bash theme={null}
X-API-Key: ca_your_api_key_here
```

## Query Parameters

| Parameter        | Type    | Required | Description                                                                                                                          |
| ---------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `limit`          | integer | No       | Page size. Must be between `1` and `250`. Defaults to `100`                                                                          |
| `offset`         | integer | No       | Number of users to skip for pagination. Must be `0` or greater. Defaults to `0`                                                      |
| `user_roles`     | array   | No       | Filter by organization role. Repeat the parameter to filter by multiple roles. Allowed values: `admin`, `editor`, `member`, `viewer` |
| `include_groups` | boolean | No       | Include each user's group memberships in the response. Defaults to `false`                                                           |
| `only_active`    | boolean | No       | Only return active users. Defaults to `true`                                                                                         |

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://platform.chamelio.ai/users?limit=50&include_groups=true&user_roles=admin&user_roles=editor" \
    -H "X-API-Key: ca_your_api_key_here"
  ```

  ```python Python theme={null}
  import requests

  url = "https://platform.chamelio.ai/users"
  headers = {
      "X-API-Key": "ca_your_api_key_here"
  }
  params = {
      "limit": 50,
      "include_groups": True,
      "user_roles": ["admin", "editor"]
  }

  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    limit: "50",
    include_groups: "true"
  });
  params.append("user_roles", "admin");
  params.append("user_roles", "editor");

  const response = await fetch(`https://platform.chamelio.ai/users?${params}`, {
    method: 'GET',
    headers: {
      'X-API-Key': 'ca_your_api_key_here'
    }
  });

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Response

### Success Response

**Status Code:** `200 OK`

```json theme={null}
{
  "users": [
    {
      "user_id": 1001,
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "role": "admin",
      "user_type": "HUMAN",
      "created_at": "2025-01-15T09:30:00Z",
      "groups": [
        {
          "group_id": 12,
          "name": "Legal"
        }
      ]
    },
    {
      "user_id": 1002,
      "email": "jane.roe@example.com",
      "first_name": "Jane",
      "last_name": "Roe",
      "role": "editor",
      "user_type": "HUMAN",
      "created_at": "2025-02-03T14:05:00Z",
      "groups": []
    }
  ],
  "total_count": 2
}
```

### Response Fields

| Field         | Type    | Description                                                                     |
| ------------- | ------- | ------------------------------------------------------------------------------- |
| `users`       | array   | List of users matching the request. Each entry is a [User Object](#user-object) |
| `total_count` | integer | Total number of users matching the filters, ignoring pagination                 |

### User Object

Each object in the `users` array contains:

| Field        | Type    | Description                                                                                                                                                          |
| ------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_id`    | integer | Unique identifier of the user                                                                                                                                        |
| `email`      | string  | Email address of the user                                                                                                                                            |
| `first_name` | string  | First name of the user                                                                                                                                               |
| `last_name`  | string  | Last name of the user                                                                                                                                                |
| `role`       | string  | Organization role. One of `admin`, `editor`, `member`, `viewer`                                                                                                      |
| `user_type`  | string  | Type of the user. One of `HUMAN`, `AGENT`, `SYSTEM_ACCOUNT`                                                                                                          |
| `created_at` | string  | ISO 8601 timestamp of when the user was created                                                                                                                      |
| `groups`     | array   | The user's group memberships. Populated only when `include_groups=true`; otherwise an empty array. Each entry is a [Group Reference Object](#group-reference-object) |

### Group Reference Object

Each object in a user's `groups` array contains:

| Field      | Type    | Description                    |
| ---------- | ------- | ------------------------------ |
| `group_id` | integer | Unique identifier of the group |
| `name`     | string  | Name of the group              |

## Error Responses

### 401 Unauthorized

Returned when authentication fails. See the [authentication errors](/api-reference/introduction#authentication-errors) section for details.

```json theme={null}
{
  "detail": "Invalid API key"
}
```

### 404 Not Found

Returned when the organization associated with the API key cannot be found.

```json theme={null}
{
  "detail": "Not found"
}
```

### 500 Internal Server Error

Returned when the users could not be retrieved due to a server error.

```json theme={null}
{
  "detail": "Failed to list users"
}
```

## Notes

<Info>
  Set `include_groups=true` only when you need group memberships — the `groups` array is empty otherwise. Use `total_count` together with `limit` and `offset` to page through large result sets.
</Info>

## Use Cases

This endpoint is useful for:

* **User directory sync** - Mirror your organization's users into an external system
* **Role-based reporting** - Filter users by role to audit access levels
* **Group membership lookup** - Retrieve which groups each user belongs to