# Get conversations

`GET https://api.chat-data.com/api/v2/get-conversations/{chatbotId}`

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

## 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 conversations from a chatbot, most recently active first. Only conversations with at least one user message are returned. Results are paginated.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| chatbotId | path | string | yes | The unique identifier allocated to the chatbot. |
| startTimestamp | query | number | no | Start of the time range (inclusive), in milliseconds since the Unix epoch. A conversation matches when it was created or last active within the range. |
| endTimestamp | query | number | no | End of the time range (exclusive), in milliseconds since the Unix epoch. |
| start | query | number | no | The start position of the results, used for pagination. |
| size | query | number | no | The maximum number of results returned after the start position, used for pagination. A negative value returns all remaining results. |
| source | query | array of string | no | Filter conversations by source. Repeat the parameter to match several sources. |
| leadId | query | string | no | The UUID of the lead, which can be obtained from the `lead-submission` webhook event. |
| requestedLiveChat | query | boolean | no | `true` returns only conversations that requested live chat support, `false` only those that did not. |
| liveChatEnded | query | boolean | no | `true` returns only conversations whose live chat has ended, `false` only those whose live chat has not ended. |
| overalRating | query | number | no | Filter conversations by their overall rating (1-5). |

## Example request

```bash
curl 'https://api.chat-data.com/api/v2/get-conversations/6650f1c2a9e4b83d2c7a1f05' \
  -H "Authorization: Bearer $CHAT_DATA_API_KEY"
```

## Example response (200)

```json
{
  "status": "success",
  "conversations": [
    {
      "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"
    }
  ],
  "total": 10
}
```

## 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 the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another 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. |