Skip to main content

​
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

ParameterTypeRequiredDescription
limitintegerNoPage size. Must be between 1 and 250. Defaults to 100
offsetintegerNoNumber of users to skip for pagination. Must be 0 or greater. Defaults to 0
user_rolesarrayNoFilter by organization role. Repeat the parameter to filter by multiple roles. Allowed values: admin, editor, member, viewer
include_groupsbooleanNoInclude each user’s group memberships in the response. Defaults to false
only_activebooleanNoOnly 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

FieldTypeDescription
usersarrayList of users matching the request. Each entry is a User Object
total_countintegerTotal number of users matching the filters, ignoring pagination

​
User Object

Each object in the users array contains:
FieldTypeDescription
user_idintegerUnique identifier of the user
emailstringEmail address of the user
first_namestringFirst name of the user
last_namestringLast name of the user
rolestringOrganization role. One of admin, editor, member, viewer
user_typestringType of the user. One of HUMAN, AGENT, SYSTEM_ACCOUNT
created_atstringISO 8601 timestamp of when the user was created
groupsarrayThe 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:
FieldTypeDescription
group_idintegerUnique identifier of the group
namestringName 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