List Users

Endpoint

GET /users

Authentication

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

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

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"

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

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

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

401 Unauthorized

Returned when authentication fails. See the authentication errors section for details.

{
  "detail": "Invalid API key"
}

404 Not Found

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

{
  "detail": "Not found"
}

500 Internal Server Error

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

{
  "detail": "Failed to list users"
}

Notes

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

401 Unauthorized

404 Not Found

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

​401 Unauthorized

​404 Not Found

​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

401 Unauthorized

404 Not Found

500 Internal Server Error

Notes

Use Cases