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

# List Conversations

> Retrieve imported conversations for a connection.

## `GET /api/conversations?connectionId=`

Lists imported conversations for a given connection, with pagination. Results are ordered by `update_time` descending (newest first).

## Request

**Headers**

| Header          | Value                    |
| --------------- | ------------------------ |
| `Authorization` | `Bearer YOUR_APP_SECRET` |

**Query parameters**

| Param          | Type     | Required | Default | Description                          |
| -------------- | -------- | -------- | ------- | ------------------------------------ |
| `connectionId` | `string` | Yes      | —       | The connection UUID                  |
| `limit`        | `number` | No       | `50`    | Max results per page (capped at 100) |
| `offset`       | `number` | No       | `0`     | Number of results to skip            |

**Example**

```bash theme={null}
curl -s https://connect.tryverso.ai/api/conversations \
  -H "Authorization: Bearer $VERSO_SECRET" \
  -G -d "connectionId=CONNECTION_ID" \
  -d "limit=50" \
  -d "offset=0"
```

## Response

```json theme={null}
{
  "conversations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "external_id": "chatgpt-abc123",
      "title": "Help me build a REST API",
      "payload": {
        "title": "Help me build a REST API",
        "messages": [
          {
            "role": "user",
            "content": "I need a REST API for managing tasks...",
            "timestamp": "2026-09-20T10:00:00Z"
          },
          {
            "role": "assistant",
            "content": "I'll help you build a task management API...",
            "timestamp": "2026-09-20T10:00:05Z"
          }
        ]
      },
      "update_time": "2026-09-20T10:05:00Z"
    }
  ],
  "total": 142,
  "limit": 50,
  "offset": 0
}
```

| Field                              | Type      | Description                                              |
| ---------------------------------- | --------- | -------------------------------------------------------- |
| `conversations`                    | `array`   | List of conversation objects                             |
| `conversations[].id`               | `string`  | Internal Verso UUID                                      |
| `conversations[].external_id`      | `string`  | Provider's conversation ID                               |
| `conversations[].title`            | `string?` | Conversation title                                       |
| `conversations[].payload`          | `object?` | Full conversation data with `title` and `messages` array |
| `conversations[].payload.messages` | `array`   | Normalized messages: `{ role, content, timestamp }`      |
| `conversations[].update_time`      | `string?` | Last update time from the provider (ISO 8601)            |
| `total`                            | `number`  | Total conversation count for this connection             |
| `limit`                            | `number`  | Requested page size                                      |
| `offset`                           | `number`  | Current offset                                           |

### Message format

Each message in `payload.messages` has this structure:

| Field       | Type      | Values                                   |
| ----------- | --------- | ---------------------------------------- |
| `role`      | `string`  | `user`, `assistant`, `system`, or `tool` |
| `content`   | `string`  | Message text                             |
| `timestamp` | `string?` | ISO 8601 timestamp (null if unavailable) |

### Pagination

Use `limit` and `offset` to paginate through results. When `offset + conversations.length >= total`, you've reached the end.

```typescript theme={null}
async function fetchAll(connectionId: string, secret: string) {
  const all = [];
  let offset = 0;
  const limit = 100; // max allowed

  while (true) {
    const res = await fetch(
      `https://connect.tryverso.ai/api/conversations?connectionId=${connectionId}&limit=${limit}&offset=${offset}`,
      { headers: { Authorization: `Bearer ${secret}` } },
    );
    const data = await res.json();
    all.push(...data.conversations);
    if (all.length >= data.total) break;
    offset += limit;
  }

  return all;
}
```

## Errors

| Status | Error                            | Cause                                                  |
| ------ | -------------------------------- | ------------------------------------------------------ |
| 400    | `Missing connectionId parameter` | `connectionId` query param not provided                |
| 401    | `Missing Authorization header`   | Missing `Bearer` prefix                                |
| 401    | `Invalid API key`                | Wrong or missing app secret                            |
| 404    | `Connection not found`           | Connection doesn't exist or belongs to a different app |
| 429    | `Rate limit exceeded`            | Exceeded 60 requests/min                               |