Skip to main content
POST
/
v3
/
list-chats
cURL
curl --request POST \
  --url https://api.retellai.com/v3/list-chats \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filter_criteria": {},
  "sort_order": "descending",
  "limit": 50,
  "skip": 0,
  "pagination_key": "<string>"
}
'
{
  "pagination_key": "<string>",
  "has_more": true,
  "items": [
    {
      "chat_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "chat_status": "ongoing",
      "version": 1,
      "retell_llm_dynamic_variables": {
        "customer_name": "John Doe"
      },
      "collected_dynamic_variables": {
        "last_node_name": "Test node"
      },
      "chat_type": "api_chat",
      "custom_attributes": {},
      "start_timestamp": 1703302407333,
      "end_timestamp": 1703302428855,
      "transcript": "Agent: hi how are you doing?\nUser: Doing pretty well. How are you?\nAgent: That's great to hear! I'm doing well too, thanks! What's up?\nUser: I don't have anything in particular.\nAgent: Got it, just checking in!\nUser: Alright. See you.\nAgent: have a nice day\n",
      "message_with_tool_calls": [
        {
          "message_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
          "role": "agent",
          "content": "hi how are you doing?",
          "created_timestamp": 1703302428855
        }
      ],
      "metadata": {},
      "chat_cost": {
        "product_costs": [
          {
            "product": "elevenlabs_tts",
            "cost": 60,
            "unit_price": 1,
            "is_transfer_leg_cost": true
          }
        ],
        "combined_cost": 70
      },
      "chat_analysis": {
        "chat_summary": "The agent messages user to ask question about his purchase inquiry. The agent asked several questions regarding his preference and asked if user would like to book an appointment. The user happily agreed and scheduled an appointment next Monday 10am.",
        "user_sentiment": "Positive",
        "chat_successful": true,
        "custom_analysis_data": {}
      }
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.retellai.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

Authorization
string
header
required

Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"

Body

application/json
filter_criteria
object

Filter criteria for chats to retrieve.

sort_order
enum<string>
default:descending

Sort chats by start_timestamp in ascending or descending order.

Available options:
ascending,
descending
limit
integer
default:50

Maximum number of chats to return.

Required range: x <= 1000
skip
integer
default:0

Number of records to skip for pagination.

Required range: x >= 0
pagination_key
string

Opaque pagination cursor from a previous response.

Response

Successfully retrieved chats.

pagination_key
string

Pagination key for the next page.

has_more
boolean

Whether more results are available.

items
object[]