# List groups

`GET /group.list`

## Description

Lists non-archived groups accessible to the caller.

Filter by name with `query` (ranked text match), restrict by group
type with `type`, and paginate with `limit` / `cursor`.

**Access:** Organization and Personal.

**Required scope:** `group:read`

---

**OpenAPI Spec:** [chat-v1.json](https://developer.ro.am/chat-v1.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `query` | query | string | No | Text filter. Groups are ranked by how well their name matches the query. |
| `type` | query | string | No | Comma-separated list of group types to include. Must be one or more of `standard`, `magicast`, `meeting`, `roam`, `onair`. Defaults to all types.  |
| `limit` | query | integer | No | Number of groups to return per page (default 50, max 100). |
| `cursor` | query | string | No | Opaque pagination cursor from a previous response's `nextCursor`. Do not construct cursors manually. |

## Responses

### 200 - Groups retrieved successfully.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `groups` | object[] | Yes |  |
| `nextCursor` | string | No | Pagination cursor for the next page. Absent when there are no more results. |

**groups** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | Yes | The group ID. |
| `name` | string | Yes |  |
| `description` | string | No | Group description, if set. |
| `imageUrl` | string | No | Group image URL, if set. |
| `type` | "standard" | "magicast" | "meeting" | "roam" | "onair" | "community" | Yes | Group type. |
| `accessMode` | "public" | "private" | No | Whether the group is public or private. |
| `dateCreated` | string | No | When the group was created (RFC3339, caller's timezone). |


#### Example Response

```json
{
  "groups": [
    {
      "id": "88bebce7-6cbb-4666-96f9-5c02d73e6661",
      "name": "All Hands",
      "description": "Company-wide announcements",
      "type": "roam",
      "accessMode": "public",
      "dateCreated": "2025-01-15T10:00:00-08:00",
      "imageUrl": "https://ro.am/card-images/88bebce7-6cbb-4666-96f9-5c02d73e6661"
    },
    {
      "id": "c6040d77-a61c-4834-a939-fe3e687ffd72",
      "name": "Engineering Team",
      "type": "standard",
      "accessMode": "public",
      "dateCreated": "2025-02-20T14:30:00-08:00",
      "imageUrl": "https://ro.am/card-images/c6040d77-a61c-4834-a939-fe3e687ffd72"
    }
  ],
  "nextCursor": "YzE6MjAyNS0wMi0yMFQxNDozMDowMFo6YzYwNDBkNzctYTYxYw"
}
```

### 400 - Bad request. Common causes:
- Invalid `limit` (non-numeric or ≤ 0)
- Invalid `cursor`
- Invalid `type` value


### 401 - Presented invalid authentication credentials.

### 405 - An unsupported method was requested.

### 500 - An internal error occurred.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/api/group-list*