Skip to main content

​
Endpoint

GET /groups

​
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 groups to skip for pagination. Must be 0 or greater. Defaults to 0
only_activebooleanNoOnly return active groups. Defaults to true

​
Request Example

curl -X GET "https://platform.chamelio.ai/groups?limit=50" \
  -H "X-API-Key: ca_your_api_key_here"

import requests

url = "https://platform.chamelio.ai/groups"
headers = {
    "X-API-Key": "ca_your_api_key_here"
}
params = {
    "limit": 50
}

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

const response = await fetch('https://platform.chamelio.ai/groups?limit=50', {
  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 
{
  "groups": [
    {
      "group_id": 12,
      "name": "Legal",
      "member_user_ids": [1001, 1002],
      "created_at": "2025-01-10T08:00:00Z"
    },
    {
      "group_id": 13,
      "name": "Procurement",
      "member_user_ids": [],
      "created_at": "2025-03-22T11:45:00Z"
    }
  ],
  "total_count": 2
}

​
Response Fields

FieldTypeDescription
groupsarrayList of groups matching the request. Each entry is a Group Object
total_countintegerTotal number of groups matching the filters, ignoring pagination

​
Group Object

Each object in the groups array contains:
FieldTypeDescription
group_idintegerUnique identifier of the group
namestringName of the group
member_user_idsarrayIdentifiers of the users who belong to the group
created_atstringISO 8601 timestamp of when the group was created

​
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 groups could not be retrieved due to a server error. 
{
  "detail": "Failed to list groups"
}

​
Notes

Use total_count together with limit and offset to page through large result sets. The member_user_ids array maps directly to the user_id values returned by GET /users.

​
Use Cases

This endpoint is useful for:
  • Group directory sync - Mirror your organization’s groups into an external system
  • Membership auditing - Review which users belong to each group
  • Access mapping - Resolve group memberships to user identifiers