List Groups

Endpoint

GET /v2/groups

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 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/v2/groups?limit=50" \
  -H "Authorization: Bearer your_access_token"

import requests

url = "https://platform.chamelio.ai/v2/groups"
headers = {
    "Authorization": "Bearer your_access_token"
}
params = {
    "limit": 50
}

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

const response = await fetch('https://platform.chamelio.ai/v2/groups?limit=50', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your_access_token'
  }
});

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

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 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 /v2/users.

The group directory is organization-wide - results are not narrowed to the groups the access token’s user belongs to.

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

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

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

Group 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