# List conversations (v2)

> Read conversations and messages with cursor pagination: list per agent, per end-user, fetch one, list messages, and export everything.

All v2 conversation reads use cursor pagination. Pass `limit` (1–100, default 20) and an opaque `cursor` from the previous page's `pagination.cursor`. Each response returns `pagination: { cursor, hasMore, total }` — when `cursor` is `null`, you have reached the end.

## GET /api/v2/agents/:agentId/conversations

List an agent's conversations, newest activity first.

| Param | In | Type | Notes |
| --- | --- | --- | --- |
| agentId | path | integer | The agent id. |
| limit | query | integer | 1–100, default 20. |
| cursor | query | string | Opaque cursor from a previous response. |

```bash
curl "https://app.bookbag.ai/api/v2/agents/123/conversations?limit=20" \
  -H "Authorization: Bearer $BOOKBAG_API_KEY"
```

## GET /api/v2/agents/:agentId/conversations/:conversationId

Fetch one conversation with a page of its messages (chronological within the page). Messages use the AI-SDK `parts` model: each part is `{ type: "text", text }` or `{ type: "tool-call", toolCallId, toolName, input }`.

```bash
curl https://app.bookbag.ai/api/v2/agents/123/conversations/456 \
  -H "Authorization: Bearer $BOOKBAG_API_KEY"
```

## GET .../conversations/:conversationId/messages

List just the messages for a conversation, with the same cursor pagination and `parts` shape. Returns `{ data: [...messages], pagination }`.

## GET /api/v2/agents/:agentId/users/:userId/conversations

List the conversations belonging to one end-user (the `userId` you sent on [chat](/docs/api/v2/chat)). Same shape and pagination as the agent list.

```bash
curl https://app.bookbag.ai/api/v2/agents/123/users/user_8821/conversations \
  -H "Authorization: Bearer $BOOKBAG_API_KEY"
```

## GET /api/v2/agents/:agentId/conversations/export

Export **all** of an agent's conversations, each with its full message list. Returns `{ data: [...], pagination: { cursor: null, hasMore: false, total } }`. Intended for bulk/offline processing rather than paging.

```bash
curl https://app.bookbag.ai/api/v2/agents/123/conversations/export \
  -H "Authorization: Bearer $BOOKBAG_API_KEY"
```

## Status codes

| Status | Code | Meaning |
| --- | --- | --- |
| 200 | — | Success. |
| 401 | AUTH_MISSING_API_KEY / AUTH_INVALID_API_KEY | Missing or invalid key. |
| 403 | AUTH_INSUFFICIENT_PERMISSIONS | Agent-scoped key targeting a different agent. |
| 404 | RESOURCE_NOT_FOUND | Agent or conversation not found / out of scope. |
| 429 | RATE_LIMIT_TOO_MANY_REQUESTS | Rate limit exceeded. |

See [Errors](/docs/api/errors).