> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chamelio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Groups

> Retrieve the user groups defined in your Chamelio organization with pagination and an option to include only active groups for access management.

## Endpoint

```
GET /groups
```

## Authentication

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

```bash theme={null}
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

```bash cURL theme={null}
curl -X GET "https://platform.chamelio.ai/groups?limit=50" \
  -H "X-API-Key: ca_your_api_key_here"
```

```python Python theme={null}
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())
```

```javascript JavaScript theme={null}
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`

```json theme={null}
{
  "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](#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](https://docs.chamelio.ai/api-reference/api-keys.md#authentication-errors) section for details.

```json theme={null}
{
  "detail": "Invalid API key"
}
```

### 404 Not Found

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

```json theme={null}
{
  "detail": "Not found"
}
```

### 500 Internal Server Error

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

```json theme={null}
{
  "detail": "Failed to list groups"
}
```

## Notes

> [!NOTE]
>
> 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`](https://docs.chamelio.ai/api-reference/endpoint/users/list).

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