# List an agent's finished chat conversations (/docs/api/voice-agents/chat-conversations/listFinishedChatConversations)

> For the complete documentation index, see [llms.txt](https://docs.tandemcx.ai/llms.txt). Any page on this site can be fetched as Markdown by appending `.md` to its URL.

`GET /v1/agent-media/chat-conversations`

List an agent's finished chat conversations

Website chat conversations that are no longer live, newest activity first — chat's equivalent of an agent's completed calls.

Deliberately the COMPLEMENT of the live conversations collection: a chat appears in one or the other and never both. A chat leaves the live collection when the agent finishes it, when it reaches its message limit, or when nothing has been said for 30 minutes, and it appears here from that moment until its 90-day retention expires.

`endedAt` is present when the agent actually finished the conversation and absent when it simply fell quiet — two different facts, so a quiet conversation carries no invented end time.

## Request

**Base URL:** `https://api.tandemcx.ai`

**Authentication:** `Authorization: Bearer <token>` — A Tandem bearer token. Requests are scoped to the organization the token belongs to; no organization header is required.

### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `agentId` | string | Yes | The agent whose conversations to list. |
| `limit` | integer | No | Page size. A larger value is clamped to the maximum rather than refused. |
| `cursor` | string | No | The `nextCursor` from a previous page. An unreadable cursor starts from the beginning rather than failing the request. |

## Responses

### 200 — One page of finished conversations.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `conversations` | array of object | No | — |
| `conversations[].conversationId` | string | No | — |
| `conversations[].widgetId` | string | No | Which of the agent's chat widgets the visitor arrived through. |
| `conversations[].startedAt` | string (date-time) | No | — |
| `conversations[].lastActivityAt` | string (date-time) | No | The last message. What this collection is ordered by. |
| `conversations[].endedAt` | string (date-time) | No | When the agent finished the conversation. ABSENT when it was never finished and simply fell quiet — the two are different facts and a quiet conversation is not given an invented end time. |
| `conversations[].disposition` | string | No | The agent's own classification, when it gave one. Absent otherwise. |
| `conversations[].turnCount` | integer | No | — |
| `nextCursor` | string | No | Absent on the last page. |

### 400 — The request was malformed. `error` names the reason, such as `invalid_agentId`, `invalid_version`, `invalid_slot`, or `invalid_prompt`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | string | No | A stable machine-readable code. |
| `message` | string | No | A human-readable explanation, safe to show to an end user. Present on errors an operator can act on; browser clients display this field in preference to a generic fallback. |
| `limit` | integer | No | Present on some errors (e.g. `prompt_too_long`) that reject a value against a fixed bound: the bound itself. |
| `length` | integer | No | Present on some errors (e.g. `prompt_too_long`) that reject a value against a fixed bound: the measured size of the rejected value. |
| `reason` | string | No | Present on some errors (e.g. `invalid_avatar_image`) that have more than one cause: which one applied. |

### 401 — Missing, malformed, or expired bearer token.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | string | No | A stable machine-readable code. |
| `message` | string | No | A human-readable explanation, safe to show to an end user. Present on errors an operator can act on; browser clients display this field in preference to a generic fallback. |
| `limit` | integer | No | Present on some errors (e.g. `prompt_too_long`) that reject a value against a fixed bound: the bound itself. |
| `length` | integer | No | Present on some errors (e.g. `prompt_too_long`) that reject a value against a fixed bound: the measured size of the rejected value. |
| `reason` | string | No | Present on some errors (e.g. `invalid_avatar_image`) that have more than one cause: which one applied. |