# List chats

`GET /chat.list`

## Description

List all accessible chats, which consist of all DMs, MultiDMs, and Channels
that your bot has been added to, in addition to all public groups regardless
of membership.

Chats are returned in reverse chronological order of the chat's start
timestamp, so the first page of results contains the most recently started
chats.

**Access:** Organization only.

**Required scope:** `chat:read`

---

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

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `limit` | query | integer | No | The number of chats to return per response. Default is 10. |
| `cursor` | query | string | No | Opaque pagination cursor from a previous response's `nextCursor`. Do not construct cursors manually. |

## Responses

### 200 - Info retrieved successfully

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `chats` | object[] | No |  |

**chats** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | TaggedUUID | Yes | The Chat ID |
| `started` | string | Yes | Timestamp that the chat started |
| `group` | TaggedUUID | No | The Group ID. **Only present for channel chats** (group conversations). Absent for DMs and Multi-DMs.  |
| `name` | string | Yes | Descriptive name for the chat, set as follows:  * Channel - the group name * DM - the name of the other party. * Multi-DM, a comma separated list of all participant names.  |

**TaggedUUID**:

A UUID prefixed by a tag identifying the specific type of object
**TaggedUUID**:

*See TaggedUUID above*


#### Example Response

```json
{
  "chats": [
    {
      "id": "C-295155ae-7df5-4ed5-9ebc-89a170559c81",
      "started": "2025-12-13T05:07:54Z",
      "name": "Engineering Team",
      "group": "G-88bebce7-6cbb-4666-96f9-5c02d73e6661"
    },
    {
      "id": "C-f2976612-ffdc-4240-8ff6-6dda54bc4917",
      "started": "2025-11-13T22:21:51Z",
      "name": "Sales Team",
      "group": "G-c6040d77-a61c-4834-a939-fe3e687ffd72"
    },
    {
      "id": "D-53b8a72b-b442-4da2-94ea-41b6116c14ea",
      "started": "2025-10-18T23:29:25Z",
      "name": "Alex Chen"
    }
  ],
  "nextCursor": "1760830165105000"
}
```

### 400 - Bad request.

### 401 - Presented invalid authentication credentials.

### 405 - An unsupported method was requested.

### 500 - An internal error occured.

---

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