> ## 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 /v2/users
```
## Authentication
This endpoint requires an OAuth access token. Send it as a bearer token:
```bash theme={null}
Authorization: Bearer your_access_token
```
**Required scope:** `users:read`
## 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
```bash cURL theme={null}
curl -X GET "https://platform.chamelio.ai/v2/users?limit=50&include_groups=true&user_roles=admin&user_roles=editor" \
-H "Authorization: Bearer your_access_token"
```
```python Python theme={null}
import requests
url = "https://platform.chamelio.ai/v2/users"
headers = {
"Authorization": "Bearer your_access_token"
}
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/v2/users?${params}`, {
method: 'GET',
headers: {
'Authorization': 'Bearer your_access_token'
}
});
const data = await response.json();
console.log(data);
```
## 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
### 400 Bad Request
Returned when the access token has no user behind it.
`client_credentials` tokens act as the admin who created the application, so this applies only to
tokens issued before application creators were recorded.
```json theme={null}
{
"detail": "client_credentials tokens are not associated with a user"
}
```
### 401 Unauthorized
Returned when the access token is missing, unknown, revoked, or expired, or when an `X-API-Key` was
sent instead of a bearer token. See [OAuth error responses](/api-reference/oauth-apps#error-responses).
```json theme={null}
{
"detail": "Invalid access token"
}
```
### 403 Forbidden
Returned when the token does not carry the required scope.
```json theme={null}
{
"detail": "Insufficient scope; this endpoint requires: users:read"
}
```
### 404 Not Found
Returned when the organization cannot be found.
```json theme={null}
{
"detail": "Not found"
}
```
### 422 Unprocessable Entity
Returned when a query parameter fails validation (for example, `limit` outside the `1`–`250` range
or a non-numeric `offset`).
```json theme={null}
{
"detail": [
{
"loc": ["query", "limit"],
"msg": "Input should be less than or equal to 250",
"type": "less_than_equal"
}
]
}
```
### 429 Too Many Requests
Returned when your organization exceeds its per-minute request limit.
```json theme={null}
{
"detail": "Rate limit exceeded"
}
```
### 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
The user directory is organization-wide. Unlike tasks and workflows, results are not narrowed to what the
access token's user can see - `users:read` grants the whole directory.
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.
## 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
* **Mention pickers** - Resolve user IDs for `mention_user_ids` when adding comments
* **Group membership lookup** - Retrieve which groups each user belongs to