Conversational AI API Reference Endpoint: GET /v1/convai/conversations
Description: Retrieve all conversations of agents owned by the user. Optionally filter by agent.
cURL:
curl https://api.elevenlabs.io/v1/convai/conversations
Headers
Header
Type
Required
Description
xi-api-key
string
Optional
API authentication key
Parameter
Type
Required
Description
cursor
string
Optional
Used for fetching next page. Cursor is returned in response.
agent_id
string
Optional
ID of the agent to filter conversations.
call_successful
enum
Optional
Result of call evaluation. Values: success, failure, unknown
call_start_before_unix
integer
Optional
Filter conversations up to this start date (unix timestamp in seconds).
call_start_after_unix
integer
Optional
Filter conversations after this start date (unix timestamp in seconds).
page_size
integer
Optional
Max conversations to return (1-100). Default is 30.
{
"conversations" : [
{
"agent_id" : " agent_id" "conversation_id" : " conversation_id" "start_time_unix_secs" : 1 ,
"call_duration_secs" : 1 ,
"message_count" : 1 ,
"status" : " in-progress" "call_successful" : " success" "agent_name" : " agent_name" "has_more" : true ,
"next_cursor" : " next_cursor"
Field
Type
Description
conversations
list
List of conversation objects
├─ agent_id
string
ID of the agent
├─ conversation_id
string
Unique ID of the conversation
├─ start_time_unix_secs
int
Start time in Unix seconds
├─ call_duration_secs
int
Duration of call in seconds
├─ message_count
int
Number of messages in the conversation
├─ status
enum
One of: in-progress, processing, done, failed
├─ call_successful
enum
One of: success, failure, unknown
└─ agent_name
string
(Optional) Name of the agent
has_more
boolean
Indicates if more results exist
next_cursor
string
Cursor for next page (Optional)
Code
Meaning
422
Conversational AI Get Conversations Request Unprocessable Entity Error
Endpoint: GET /v1/convai/conversations/{conversation_id}
Description: Retrieve details of a specific conversation.
cURL:
curl https://api.elevenlabs.io/v1/convai/conversations/123
Parameter
Type
Required
Description
conversation_id
string
Yes
ID of the conversation to retrieve
Headers
Header
Type
Required
Description
xi-api-key
string
Optional
API authentication key
{
"agent_id" : " 123" "conversation_id" : " 123" "status" : " processing" "transcript" : [
{
"role" : " user" "time_in_call_secs" : 10 ,
"message" : " Hello, how are you?" "tool_calls" : [
{
"request_id" : " req-1" "tool_name" : " weather" "params_as_json" : " {\" city\" :\" NYC\" }" "tool_has_been_called" : true ,
"type" : " client" "tool_details" : {
"type" : " client" "parameters" : " {\" mode\" :\" live\" }" "tool_results" : [
{
"request_id" : " req-1" "tool_name" : " weather" "result_value" : " sunny" "is_error" : false ,
"tool_has_been_called" : true ,
"type" : " client" "tool_latency_secs" : 0.34
}
],
"feedback" : {
"score" : " like" "time_in_call_secs" : 10
},
"llm_override" : " gpt-4" "conversation_turn_metrics" : {
"metrics" : {
"latency" : 0.4 ,
"token_usage" : 150
}
},
"rag_retrieval_info" : {
"chunks" : [
{
"document_id" : " doc-1" "chunk_id" : " chunk-1" "vector_distance" : 0.12
}
],
"embedding_model" : " e5_mistral_7b_instruct" "retrieval_query" : " weather in NYC" "rag_latency_secs" : 0.2
}
}
],
"metadata" : {
"start_time_unix_secs" : 1714423232 ,
"call_duration_secs" : 10 ,
"accepted_time_unix_secs" : 1714423240 ,
"cost" : 20 ,
"deletion_settings" : {
"deletion_time_unix_secs" : 1715000000 ,
"deleted_logs_at_time_unix_secs" : 0 ,
"deleted_audio_at_time_unix_secs" : 0 ,
"deleted_transcript_at_time_unix_secs" : 0 ,
"delete_transcript_and_pii" : false ,
"delete_audio" : false
},
"feedback" : {
"overall_score" : " like" "likes" : 1 ,
"dislikes" : 0
},
"authorization_method" : " authorization_header" "charging" : {
"dev_discount" : false ,
"tier" : " pro" "llm_usage" : {
"irreversible_generation" : {},
"initiated_generation" : {
"model_usage" : {
"gpt-4" : {
"tokens" : 200 ,
"latency" : 0.8 ,
"cost" : 0.01
}
}
}
},
"llm_price" : 0.01
},
"batch_call" : {
"batch_call_id" : " batch-xyz" "batch_call_recipient_id" : " rec-abc" "termination_reason" : " completed" "error" : {
"code" : 0 ,
"reason" : " " "main_language" : " en" "rag_usage" : {
"usage_count" : 1 ,
"embedding_model" : " e5_mistral_7b_instruct" "has_audio" : true ,
"has_user_audio" : true ,
"has_response_audio" : true ,
"analysis" : {
"call_successful" : " success" "transcript_summary" : " User asked about weather in NYC." "evaluation_criteria_results" : {},
"data_collection_results" : {
"data_collection_id" : " data-1" "rationale" : " To assess sentiment" "value" : true ,
"json_schema" : {
"type" : " boolean" "description" : " Was the user positive?" "dynamic_variable" : " sentiment_result" "constant_value" : true
}
}
},
"conversation_initiation_client_data" : {
"conversation_config_override" : {
"agent" : {
"prompt" : {
"prompt" : " You are a helpful assistant." "first_message" : " Hi there! How can I assist you today?" "language" : " en" "tts" : {
"voice_id" : " voice-123" "custom_llm_extra_body" : {
"context" : " weather domain" "dynamic_variables" : {
"city" : " NYC" "temp_threshold" : 25 ,
"is_raining" : false
}
}
}
Code
Meaning
422
Conversational AI Get Conversation Request Unprocessable Entity Error
{
"detail" : [
{
"loc" : [" string" 0 ],
"msg" : " Error message" "type" : " error_type" # Get Conversation Audio
Retrieve the audio recording of a specific conversation.
## HTTP Request
GET https://api.elevenlabs.io/v1/convai/conversations/:conversation_id/audio
curl https://api.elevenlabs.io/v1/convai/conversations/{conversation_id}/audio \
-H "xi-api-key: YOUR_API_KEY"
Name
Type
Description
conversation_id
string
Required . The ID of the conversation to retrieve audio from.
Headers
Name
Type
Description
xi-api-key
string
Optional . API key for authentication.
Returns the audio recording of the requested conversation upon successful request.
422 Validation Error: Unprocessable Entity
Property
Type
Description
detail
list of objects (Optional )
Details of validation errors.
detail[].loc
list
Location of the error.
detail[].msg
string
Description of the error.
detail[].type
string
Type/category of error.
