# List conversations

`GET /conversation.list`

## Description

Lists conversations (meetings) that occurred in your Roam, with participant details.

**Access:**
- **Organization with [`admin:meetings:read`](/docs/guides/scopes#meeting-width-adminmeetingsread)**
  (or a grandfathered roam-wide API key): all conversations in the workspace.
- **Personal access tokens:** supported — returns only conversations the
  token owner participated in (matched by confirmed email).
- **Organization without roam-wide meeting access** must use
  [`/meeting.list`](/docs/api/meeting-list) instead (`403`).

**Required scope:** `meetings:read` (add `admin:meetings:read` for roam-wide org access)

Participant details require `user:read` scope. Email addresses require `user:read.email` scope.

---

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

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `before` | query | string | No | Only return conversations that started before this ISO-8601 timestamp. |
| `after` | query | string | No | Only return conversations that started after this ISO-8601 timestamp. |
| `ascending` | query | boolean | No | Sort results in ascending order by start time. Default is descending (newest first). |
| `limit` | query | integer | No | The number of conversations to return per response. |
| `cursor` | query | string | No | Opaque pagination cursor from a previous response's `nextCursor`. Do not construct cursors manually. |

## Responses

### 200 - Conversations retrieved successfully

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `conversations` | object[] | No |  |
| `nextCursor` | string | No | Pagination cursor for fetching the next page of results |

**conversations** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | No | Unique identifier for the conversation (meeting GUID) |
| `place` | string | No | The place where the conversation occurred |
| `room` | string | No | The room name |
| `roomType` | string | No | The type of room |
| `start` | string | No | When the conversation started (ISO-8601) |
| `end` | string | No | When the conversation ended (ISO-8601) |
| `participants` | object[] | No | List of participants (requires `user:read` scope) |
| `meetingLinkIds` | string[] | No | IDs of meeting links associated with this conversation |

**participants** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | string | No | Display name of the participant |
| `email` | string | No | Email address (requires `user:read.email` scope) |
| `seconds` | number | No | Duration the participant was in the conversation, in seconds |


#### Example Response

```json
{
  "conversations": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "place": "Headquarters",
      "room": "Conference Room A",
      "roomType": "meeting",
      "start": "2025-03-15T14:00:00Z",
      "end": "2025-03-15T14:45:00Z",
      "participants": [
        {
          "name": "Alex Chen",
          "email": "alex.chen@example.com",
          "seconds": 2700
        },
        {
          "name": "Jordan Smith",
          "email": "jordan.smith@example.com",
          "seconds": 2400
        }
      ],
      "meetingLinkIds": []
    }
  ],
  "nextCursor": "YzE6MjAyNS0wMy0xNVQxNDowMDowMFo"
}
```

### 400 - Bad request.

### 401 - Presented invalid authentication credentials.

### 403 - Forbidden. Either a personal access token was used (an account-level
token is required), or the org client does not have roam-wide meeting
access (`admin:meetings:read`). Use [`/meeting.list`](/docs/api/meeting-list)
instead.


### 500 - An internal error occurred.

---

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