List Groups

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

Parameter	Type	Required	Description
`limit`	integer	No	Page size. Must be between `1` and `250`. Defaults to `100`
`offset`	integer	No	Number of groups to skip for pagination. Must be `0` or greater. Defaults to `0`
`only_active`	boolean	No	Only 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

Field	Type	Description
`groups`	array	List of groups matching the request. Each entry is a Group Object
`total_count`	integer	Total number of groups matching the filters, ignoring pagination

Group Object

Each object in the groups array contains:

Field	Type	Description
`group_id`	integer	Unique identifier of the group
`name`	string	Name of the group
`member_user_ids`	array	Identifiers of the users who belong to the group
`created_at`	string	ISO 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

Overview

API Key Access

OAuth App Access

Webhooks

Endpoint

Authentication

Query Parameters

Request Example

Response

Success Response

Response Fields

Group 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

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

Group Object

Error Responses

401 Unauthorized

404 Not Found

500 Internal Server Error

Notes

Use Cases