# Get a conversation

`GET https://api.chat-data.com/api/v2/get-conversation/{conversationId}`

Canonical: https://www.chat-data.com/api-reference/get-conversation

## Authentication

Send an API key as a Bearer token: `Authorization: Bearer $CHAT_DATA_API_KEY`. Workspace keys reach every chatbot in the workspace; chatbot-scoped keys reach only their chatbot. Keep keys on the server.

## Description

Get detailed information about a specific conversation, including messages, customer details if available, and metadata.

If `chatbotId` is provided, the conversation is retrieved from that chatbot.
If `chatbotId` is not provided, the conversation is retrieved from any chatbot in your workspace (or, with a chatbot-scoped key, from that key's chatbot).

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| conversationId | path | string | yes | The unique identifier of the conversation. |
| chatbotId | query | string | no | The unique identifier of the chatbot to retrieve the conversation from. If not provided, the conversation is retrieved from any chatbot in your workspace. |

## Example request

```bash
curl 'https://api.chat-data.com/api/v2/get-conversation/3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c' \
  -H "Authorization: Bearer $CHAT_DATA_API_KEY"
```

## Example response (200)

```json
{
  "status": "success",
  "conversation": {
    "conversationId": "3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c",
    "createdAt": 1791970200000,
    "messages": [
      {
        "role": "user",
        "content": "What are your opening hours?",
        "timestamp": "2026-10-14T09:30:00.000Z",
        "read": true
      },
      {
        "role": "assistant",
        "content": "We're open Monday to Friday, 9am to 6pm EST. Outside those hours you can email support@example.com.",
        "timestamp": "2026-10-14T09:30:03.000Z",
        "score": 0.87,
        "upvote": true,
        "read": true
      },
      {
        "role": "user",
        "content": "Thanks! Can I talk to someone about a refund?",
        "timestamp": "2026-10-14T09:31:00.000Z",
        "read": true
      },
      {
        "role": "human",
        "content": "Hi Jane, I'm Alex from the support team. I can help with your refund.",
        "name": "Alex Chen",
        "avatar": "https://example.blob.core.windows.net/chatfiles/6650f1c2a9e4b83d2c7a1f05/agent-avatar.png",
        "timestamp": "2026-10-14T09:32:00.000Z",
        "read": true
      }
    ],
    "source": "widget",
    "requestedLiveChat": true,
    "liveChatEnded": false,
    "chatbotId": "6650f1c2a9e4b83d2c7a1f05",
    "ipAddress": "203.0.113.42",
    "userCountry": "US",
    "customer": {
      "leadId": "8d0c2b6e-4f1a-4b7c-9e3d-2a5f6b7c8d9e",
      "name": "Jane Doe",
      "email": "jane@chat-data.com",
      "phone": "+14155550123",
      "createdAt": 1791970230000
    },
    "overalRating": 5,
    "browserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0 Safari/537.36",
    "urlPath": "/pricing"
  }
}
```

## Responses

| Status | Description |
| --- | --- |
| 200 | Successful response. |
| 400 | An unexpected error occurred while processing the request; `message` contains the error. |
| 401 | Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which. |
| 403 | The API key cannot access this conversation. With a `chatbotId` query parameter, a chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`, and any key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when that chatbot does not exist or belongs to another workspace. |
| 404 | No conversation with this ID was found in the key's workspace (or in the given or key's chatbot), including one that belongs to another chatbot or workspace. |
| 429 | The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying. |