> ## 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 in your organization, with pagination and an option to include only active groups.

## Endpoint

```
GET /v2/groups
```

## Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:

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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://platform.chamelio.ai/v2/groups?limit=50" \
    -H "Authorization: Bearer your_access_token"
  ```

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

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

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

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

```json theme={null}
{
  "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](/api-reference/oauth-apps#error-responses).

```json theme={null}
{
  "detail": "Invalid access token"
}
```

### 403 Forbidden

Returned when the token does not carry the required scope.

```json theme={null}
{
  "detail": "Insufficient scope; this endpoint requires: users:read"
}
```

### 404 Not Found

Returned when the organization cannot be found.

```json theme={null}
{
  "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`).

```json theme={null}
{
  "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.

```json theme={null}
{
  "detail": "Rate limit exceeded"
}
```

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

<Info>
  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`](/api-reference/endpoint/v2/users/list).
</Info>

<Info>
  The group directory is organization-wide - results are not narrowed to the groups the access token's
  user belongs to.
</Info>

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