Skip to main content

​
List Conversations

Retrieve a list of conversations for agents belonging to the authenticated user.
​
query
string
Filter conversations by agent ID
​
query
integer
default:"30"
Number of conversations to return per page (1-100)
​
query
string
Filter by call success status: ‘success’ or ‘failure’
​
query
integer
Filter conversations started before this Unix timestamp
​
query
integer
Filter conversations started after this Unix timestamp
​
query
string
Filter by user ID
​
query
string
default:"include"
Include summary in response: ‘include’ or ‘exclude’
​
query
string
Pagination cursor for next page
curl -X GET "https://api.example.com/api/v1/conversations?agent_id=123&page_size=20&call_successful=success" \
  -H "X-API-Key: your-api-key-here"

​
Response

​
status
object
Response status information
​
code
integer
HTTP status code (200)
​
message
string
Status message
​
data
array
Array of conversation objects
​
conversation_id
string
Unique conversation identifier
​
agent_id
string
Associated agent ID
​
agent_name
string
Name of the agent
​
status
string
Conversation status
​
transcript
array
Array of conversation transcript entries
​
metadata
object
Additional conversation metadata
​
created_at
string
ISO 8601 timestamp when conversation started
​
total_count
integer
Total number of conversations matching the query
​
cursor
string
Pagination cursor for the next page
​
has_more
boolean
Whether there are more results available
{
  "status": {
    "code": 200,
    "message": "Success"
  },
  "data": [
    {
      "conversation_id": "conv_abc123",
      "agent_id": "123",
      "agent_name": "Customer Support Agent",
      "status": "completed",
      "transcript": [
        {
          "role": "user",
          "content": "Hello, I need help with my order",
          "timestamp": "2024-01-15T10:30:00Z"
        },
        {
          "role": "assistant",
          "content": "I'd be happy to help you with your order. Can you provide your order number?",
          "timestamp": "2024-01-15T10:30:05Z"
        }
      ],
      "metadata": {
        "duration": 120,
        "call_quality": "good"
      },
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total_count": 1,
  "cursor": "eyJpZCI6IjEyMyJ9",
  "has_more": false
}

​
Pagination

Use the cursor field from the response to fetch the next page: 
curl -X GET "https://api.example.com/api/v1/conversations?cursor=eyJpZCI6IjEyMyJ9" \
  -H "X-API-Key: your-api-key-here"

​
Error Responses

​
401
object
Unauthorized - Invalid or missing authentication
​
400
object
Bad request - Missing API key or invalid parameters
​
502
object
Bad gateway - ElevenLabs API error