Chat
List Chats
List chats with unified cursor pagination response.
POST
/
v3
/
list-chats
JavaScript
import Retell from 'retell-sdk';
const client = new Retell({
apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted
});
const chats = await client.chat.list();
console.log(chats.has_more);import os
from retell import Retell
client = Retell(
api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted
)
chats = client.chat.list()
print(chats.has_more)curl --request POST \
--url https://api.retellai.com/v3/list-chats \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"filter_criteria": {
"agent": [
{
"agent_id": "<string>",
"version": [
123
]
}
],
"chat_id": {
"type": "string",
"value": "<string>"
},
"start_timestamp": {
"type": "number",
"value": 123
},
"end_timestamp": {
"type": "number",
"value": 123
},
"duration_ms": {
"type": "number",
"value": 123
},
"combined_cost": {
"type": "number",
"value": 123
},
"custom_analysis_data": [
{
"type": "string",
"value": "<string>",
"key": "<string>"
}
],
"custom_attributes": [
{
"type": "string",
"value": "<string>",
"key": "<string>"
}
]
},
"sort_order": "descending",
"limit": 50,
"skip": 0,
"pagination_key": "<string>",
"include_total": false
}
'<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.retellai.com/v3/list-chats",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'filter_criteria' => [
'agent' => [
[
'agent_id' => '<string>',
'version' => [
123
]
]
],
'chat_id' => [
'type' => 'string',
'value' => '<string>'
],
'start_timestamp' => [
'type' => 'number',
'value' => 123
],
'end_timestamp' => [
'type' => 'number',
'value' => 123
],
'duration_ms' => [
'type' => 'number',
'value' => 123
],
'combined_cost' => [
'type' => 'number',
'value' => 123
],
'custom_analysis_data' => [
[
'type' => 'string',
'value' => '<string>',
'key' => '<string>'
]
],
'custom_attributes' => [
[
'type' => 'string',
'value' => '<string>',
'key' => '<string>'
]
]
],
'sort_order' => 'descending',
'limit' => 50,
'skip' => 0,
'pagination_key' => '<string>',
'include_total' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.retellai.com/v3/list-chats"
payload := strings.NewReader("{\n \"filter_criteria\": {\n \"agent\": [\n {\n \"agent_id\": \"<string>\",\n \"version\": [\n 123\n ]\n }\n ],\n \"chat_id\": {\n \"type\": \"string\",\n \"value\": \"<string>\"\n },\n \"start_timestamp\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"end_timestamp\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"duration_ms\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"combined_cost\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"custom_analysis_data\": [\n {\n \"type\": \"string\",\n \"value\": \"<string>\",\n \"key\": \"<string>\"\n }\n ],\n \"custom_attributes\": [\n {\n \"type\": \"string\",\n \"value\": \"<string>\",\n \"key\": \"<string>\"\n }\n ]\n },\n \"sort_order\": \"descending\",\n \"limit\": 50,\n \"skip\": 0,\n \"pagination_key\": \"<string>\",\n \"include_total\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.retellai.com/v3/list-chats")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"filter_criteria\": {\n \"agent\": [\n {\n \"agent_id\": \"<string>\",\n \"version\": [\n 123\n ]\n }\n ],\n \"chat_id\": {\n \"type\": \"string\",\n \"value\": \"<string>\"\n },\n \"start_timestamp\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"end_timestamp\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"duration_ms\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"combined_cost\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"custom_analysis_data\": [\n {\n \"type\": \"string\",\n \"value\": \"<string>\",\n \"key\": \"<string>\"\n }\n ],\n \"custom_attributes\": [\n {\n \"type\": \"string\",\n \"value\": \"<string>\",\n \"key\": \"<string>\"\n }\n ]\n },\n \"sort_order\": \"descending\",\n \"limit\": 50,\n \"skip\": 0,\n \"pagination_key\": \"<string>\",\n \"include_total\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.retellai.com/v3/list-chats")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"filter_criteria\": {\n \"agent\": [\n {\n \"agent_id\": \"<string>\",\n \"version\": [\n 123\n ]\n }\n ],\n \"chat_id\": {\n \"type\": \"string\",\n \"value\": \"<string>\"\n },\n \"start_timestamp\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"end_timestamp\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"duration_ms\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"combined_cost\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"custom_analysis_data\": [\n {\n \"type\": \"string\",\n \"value\": \"<string>\",\n \"key\": \"<string>\"\n }\n ],\n \"custom_attributes\": [\n {\n \"type\": \"string\",\n \"value\": \"<string>\",\n \"key\": \"<string>\"\n }\n ]\n },\n \"sort_order\": \"descending\",\n \"limit\": 50,\n \"skip\": 0,\n \"pagination_key\": \"<string>\",\n \"include_total\": false\n}"
response = http.request(request)
puts response.read_body{
"has_more": true,
"items": [
{
"chat_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
"agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
"chat_status": "ongoing",
"is_escalated": true,
"version": 1,
"agent_tag": "prod",
"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,
"customer_defined_metadata": {
"transfer_target_name": "<string>"
},
"multimedia": [
{
"url": "<string>",
"summary": "<string>"
}
]
}
],
"pre_session_message_with_tool_calls": [
{
"message_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
"role": "agent",
"content": "hi how are you doing?",
"created_timestamp": 1703302428855,
"customer_defined_metadata": {
"transfer_target_name": "<string>"
},
"multimedia": [
{
"url": "<string>",
"summary": "<string>"
}
]
}
],
"scrubbed_pre_session_message_with_tool_calls": [
{
"message_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
"role": "agent",
"content": "hi how are you doing?",
"created_timestamp": 1703302428855,
"customer_defined_metadata": {
"transfer_target_name": "<string>"
},
"multimedia": [
{
"url": "<string>",
"summary": "<string>"
}
]
}
],
"post_session_message_with_tool_calls": [
{
"message_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
"role": "agent",
"content": "hi how are you doing?",
"created_timestamp": 1703302428855,
"customer_defined_metadata": {
"transfer_target_name": "<string>"
},
"multimedia": [
{
"url": "<string>",
"summary": "<string>"
}
]
}
],
"scrubbed_post_session_message_with_tool_calls": [
{
"message_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
"role": "agent",
"content": "hi how are you doing?",
"created_timestamp": 1703302428855,
"customer_defined_metadata": {
"transfer_target_name": "<string>"
},
"multimedia": [
{
"url": "<string>",
"summary": "<string>"
}
]
}
],
"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": {}
}
}
],
"pagination_key": "<string>",
"total": 123
}{
"status": "error",
"message": "Invalid request format, please check API reference."
}{
"status": "error",
"message": "API key is missing or invalid."
}{
"status": "error",
"message": "Account rate limited, please throttle your requests."
}{
"status": "error",
"message": "An unexpected server error occurred."
}Authorizations
Body
application/json
Was this page helpful?
⌘I
JavaScript
import Retell from 'retell-sdk';
const client = new Retell({
apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted
});
const chats = await client.chat.list();
console.log(chats.has_more);import os
from retell import Retell
client = Retell(
api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted
)
chats = client.chat.list()
print(chats.has_more)curl --request POST \
--url https://api.retellai.com/v3/list-chats \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"filter_criteria": {
"agent": [
{
"agent_id": "<string>",
"version": [
123
]
}
],
"chat_id": {
"type": "string",
"value": "<string>"
},
"start_timestamp": {
"type": "number",
"value": 123
},
"end_timestamp": {
"type": "number",
"value": 123
},
"duration_ms": {
"type": "number",
"value": 123
},
"combined_cost": {
"type": "number",
"value": 123
},
"custom_analysis_data": [
{
"type": "string",
"value": "<string>",
"key": "<string>"
}
],
"custom_attributes": [
{
"type": "string",
"value": "<string>",
"key": "<string>"
}
]
},
"sort_order": "descending",
"limit": 50,
"skip": 0,
"pagination_key": "<string>",
"include_total": false
}
'<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.retellai.com/v3/list-chats",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'filter_criteria' => [
'agent' => [
[
'agent_id' => '<string>',
'version' => [
123
]
]
],
'chat_id' => [
'type' => 'string',
'value' => '<string>'
],
'start_timestamp' => [
'type' => 'number',
'value' => 123
],
'end_timestamp' => [
'type' => 'number',
'value' => 123
],
'duration_ms' => [
'type' => 'number',
'value' => 123
],
'combined_cost' => [
'type' => 'number',
'value' => 123
],
'custom_analysis_data' => [
[
'type' => 'string',
'value' => '<string>',
'key' => '<string>'
]
],
'custom_attributes' => [
[
'type' => 'string',
'value' => '<string>',
'key' => '<string>'
]
]
],
'sort_order' => 'descending',
'limit' => 50,
'skip' => 0,
'pagination_key' => '<string>',
'include_total' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.retellai.com/v3/list-chats"
payload := strings.NewReader("{\n \"filter_criteria\": {\n \"agent\": [\n {\n \"agent_id\": \"<string>\",\n \"version\": [\n 123\n ]\n }\n ],\n \"chat_id\": {\n \"type\": \"string\",\n \"value\": \"<string>\"\n },\n \"start_timestamp\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"end_timestamp\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"duration_ms\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"combined_cost\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"custom_analysis_data\": [\n {\n \"type\": \"string\",\n \"value\": \"<string>\",\n \"key\": \"<string>\"\n }\n ],\n \"custom_attributes\": [\n {\n \"type\": \"string\",\n \"value\": \"<string>\",\n \"key\": \"<string>\"\n }\n ]\n },\n \"sort_order\": \"descending\",\n \"limit\": 50,\n \"skip\": 0,\n \"pagination_key\": \"<string>\",\n \"include_total\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.retellai.com/v3/list-chats")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"filter_criteria\": {\n \"agent\": [\n {\n \"agent_id\": \"<string>\",\n \"version\": [\n 123\n ]\n }\n ],\n \"chat_id\": {\n \"type\": \"string\",\n \"value\": \"<string>\"\n },\n \"start_timestamp\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"end_timestamp\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"duration_ms\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"combined_cost\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"custom_analysis_data\": [\n {\n \"type\": \"string\",\n \"value\": \"<string>\",\n \"key\": \"<string>\"\n }\n ],\n \"custom_attributes\": [\n {\n \"type\": \"string\",\n \"value\": \"<string>\",\n \"key\": \"<string>\"\n }\n ]\n },\n \"sort_order\": \"descending\",\n \"limit\": 50,\n \"skip\": 0,\n \"pagination_key\": \"<string>\",\n \"include_total\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.retellai.com/v3/list-chats")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"filter_criteria\": {\n \"agent\": [\n {\n \"agent_id\": \"<string>\",\n \"version\": [\n 123\n ]\n }\n ],\n \"chat_id\": {\n \"type\": \"string\",\n \"value\": \"<string>\"\n },\n \"start_timestamp\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"end_timestamp\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"duration_ms\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"combined_cost\": {\n \"type\": \"number\",\n \"value\": 123\n },\n \"custom_analysis_data\": [\n {\n \"type\": \"string\",\n \"value\": \"<string>\",\n \"key\": \"<string>\"\n }\n ],\n \"custom_attributes\": [\n {\n \"type\": \"string\",\n \"value\": \"<string>\",\n \"key\": \"<string>\"\n }\n ]\n },\n \"sort_order\": \"descending\",\n \"limit\": 50,\n \"skip\": 0,\n \"pagination_key\": \"<string>\",\n \"include_total\": false\n}"
response = http.request(request)
puts response.read_body{
"has_more": true,
"items": [
{
"chat_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
"agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
"chat_status": "ongoing",
"is_escalated": true,
"version": 1,
"agent_tag": "prod",
"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,
"customer_defined_metadata": {
"transfer_target_name": "<string>"
},
"multimedia": [
{
"url": "<string>",
"summary": "<string>"
}
]
}
],
"pre_session_message_with_tool_calls": [
{
"message_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
"role": "agent",
"content": "hi how are you doing?",
"created_timestamp": 1703302428855,
"customer_defined_metadata": {
"transfer_target_name": "<string>"
},
"multimedia": [
{
"url": "<string>",
"summary": "<string>"
}
]
}
],
"scrubbed_pre_session_message_with_tool_calls": [
{
"message_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
"role": "agent",
"content": "hi how are you doing?",
"created_timestamp": 1703302428855,
"customer_defined_metadata": {
"transfer_target_name": "<string>"
},
"multimedia": [
{
"url": "<string>",
"summary": "<string>"
}
]
}
],
"post_session_message_with_tool_calls": [
{
"message_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
"role": "agent",
"content": "hi how are you doing?",
"created_timestamp": 1703302428855,
"customer_defined_metadata": {
"transfer_target_name": "<string>"
},
"multimedia": [
{
"url": "<string>",
"summary": "<string>"
}
]
}
],
"scrubbed_post_session_message_with_tool_calls": [
{
"message_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
"role": "agent",
"content": "hi how are you doing?",
"created_timestamp": 1703302428855,
"customer_defined_metadata": {
"transfer_target_name": "<string>"
},
"multimedia": [
{
"url": "<string>",
"summary": "<string>"
}
]
}
],
"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": {}
}
}
],
"pagination_key": "<string>",
"total": 123
}{
"status": "error",
"message": "Invalid request format, please check API reference."
}{
"status": "error",
"message": "API key is missing or invalid."
}{
"status": "error",
"message": "Account rate limited, please throttle your requests."
}{
"status": "error",
"message": "An unexpected server error occurred."
}
