List Users

Endpoint

GET /v2/users

Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:

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

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"

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())

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

{
  "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
`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

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.

{
  "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.

{
  "detail": "Invalid access token"
}

403 Forbidden

Returned when the token does not carry the required scope.

{
  "detail": "Insufficient scope; this endpoint requires: users:read"
}

404 Not Found

Returned when the organization cannot be found.

{
  "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).

{
  "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.

{
  "detail": "Rate limit exceeded"
}

500 Internal Server Error

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

{
  "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

Overview

API Key Access

OAuth App Access

Webhooks

Endpoint

Authentication

Query Parameters

Request Example

Response

Success Response

Response Fields

User Object

Group Reference Object

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases

​Endpoint

​Authentication

​Query Parameters

​Request Example

​Response

​Success Response

​Response Fields

​User Object

​Group Reference Object

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​422 Unprocessable Entity

​429 Too Many Requests

​500 Internal Server Error

​Notes

​Use Cases

Endpoint

Authentication

Query Parameters

Request Example

Response

Success Response

Response Fields

User Object

Group Reference Object

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases