---
title: "Get conversations"
method: GET
path: "/get-conversations/{chatbotId}"
tags: ["Conversation Operations"]
---

# Get conversations

`GET /get-conversations/{chatbotId}`

## Request

- Base URL: `https://api.chat-data.com/api/v2`
- URL: `https://api.chat-data.com/api/v2/get-conversations/{chatbotId}`
- Auth: HTTP bearer

Get conversations from a chatbot, most recently active first. Only conversations with at least one user message are returned. Results are paginated.

## Path parameters

- `chatbotId` string, required

## Query parameters

- `startTimestamp` number: 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` number: End of the time range (exclusive), in milliseconds since the Unix epoch.
- `start` number: The start position of the results, used for pagination.
- `size` number: The maximum number of results returned after the start position, used for pagination. A negative value returns all remaining results.
- `source` string[]: Filter conversations by source. Repeat the parameter to match several sources.
- `leadId` string: The UUID of the lead, which can be obtained from the `lead-submission` webhook event.
- `requestedLiveChat` boolean: `true` returns only conversations that requested live chat support, `false` only those that did not.
- `liveChatEnded` boolean: `true` returns only conversations whose live chat has ended, `false` only those whose live chat has not ended.
- `overalRating` number: Filter conversations by their overall rating (1-5).

## Response `200`

Successful response.

- ConversationsRes
  - `status` 'success', required
  - `conversations` Conversation[], required: The conversations, most recently active first. Only conversations with at least one user message are included.
    - `conversationId` string, required: ID of the conversation.
    - `createdAt` number, required: When the conversation was created, in milliseconds since the Unix epoch.
    - `lastMessageAt` string, date-time: When the last message in the conversation was sent (ISO 8601), or when the conversation was created if that is not recorded. Only returned by get-conversation.
    - `messages` Message[], required: The messages of the conversation, oldest first.
      - `role` 'user' | 'assistant' | 'human', required: The role of the message sender (`user`, `assistant`, or `human` for a live chat agent).
      - `content` string, required: The text content of the message.
      - `isTranscript` boolean: Indicates whether the message is a transcript of the realtime voice-to-voice interaction.
      - `upvote` boolean: Indicates whether the message is upvoted by the user.
      - `name` string: The name of the agent who sent the message, if the role is `human`.
      - `avatar` string: The avatar image URL of the agent who sent the message, if the role is `human`.
      - `timestamp` string, date-time: When the message was sent (ISO 8601).
      - `mid` string: The ID of the message.
      - `reasoning` string: The model's reasoning for an assistant message, when it was recorded.
      - `downvoteFeedback` string: The user's feedback when they downvoted the message.
      - `read` boolean: Indicates whether the message has been read by the user or the agent.
      - `files` object[]: The files attached to the message.
        - `name` string, required: The name of the file.
        - `type` string, required: The MIME type of the file.
        - `url` string, uri, required: The URL of the file in Azure Blob Storage. Use the `/get-sas-token` endpoint to get a URL with a SAS token for public access.
      - `audioUrl` string: The URL of the audio file in Azure Blob Storage, when the message is a transcript of an audio input. Use the `/get-sas-token` endpoint to get a URL with a SAS token for public access.
      - `score` number: The level of confidence in the generated answer. If no score is present, the answer was not derived from search results.
    - `source` 'widget' | 'iframe' | 'site' | 'api' | 'Whatsapp' | 'WhatsappWebAPI' | 'Messenger' | 'Instagram' | 'Telegram' | 'Line' | 'Slack' | 'Discord' | 'Workflow Studio' | 'cron-trigger', required: Where the conversation took place.
    - `requestedLiveChat` boolean: Whether live chat support was requested in this conversation.
    - `liveChatEnded` boolean: Whether live chat has ended in this conversation.
    - `chatbotId` string, required: The ID of the chatbot.
    - `ipAddress` string: The IP address of the user.
    - `userCountry` string: The 2-letter ISO country code of the user, based on an IP address lookup (`Unknown` when it could not be resolved).
    - `customer` Customer: A lead. Fields that are not set are omitted, and the answers of a custom lead form are included as extra top-level fields.
      - `leadId` string: The unique identifier of the lead (UUID).
      - `name` string: The name provided by the customer.
      - `email` string: The email address provided by the customer.
      - `phone` string: The phone number provided by the customer.
      - `psid` string: The page-scoped user ID of the customer, if the customer is from Messenger.
      - `ig_username` string: The Instagram username of the customer, if the customer is from Instagram.
      - `username` string: Slack or Telegram username. A platform-specific identifier, distinct from `ig_username` (Instagram) and `psid` (Messenger).
      - `info` string: Additional information stored on the lead.
      - `source` 'widget' | 'iframe' | 'site' | 'api' | 'Whatsapp' | 'WhatsappWebAPI' | 'Messenger' | 'Instagram' | 'Telegram' | 'Line' | 'Slack' | 'Discord' | 'Workflow Studio' | 'cron-trigger': The source the customer was acquired from. Only returned by get-customers.
      - `ipAddress` string: The IP address of the customer. Only returned by get-customers.
      - `userCountry` string: The 2-letter ISO country code of the customer, based on an IP address lookup (`Unknown` when it could not be resolved). Only returned by get-customers.
      - `createdAt` number, required: When the customer's information was submitted, in milliseconds since the Unix epoch.
    - `overalRating` number: The overall rating the user gave the conversation (1-5), if any.
    - `browserAgent` string: The user agent string of the browser used in the conversation.
    - `urlPath` string: The URL path where the conversation started, when the source is `widget`.
  - `total` number, required: Total number of matching conversations, ignoring pagination.

## Other responses

- `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.

---

[API](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide.md) · [All operations](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide/llms.txt) · [OpenAPI document](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide/revisions/72871007f7f0?raw)