Get Conversations

Retrieves a paginated list of conversations with powerful filtering, searching, and sorting capabilities.

Endpoint

GET https://api.ayra.ai/v1/conversations

Authentication

Requires API key with conversations:read permission.

Query Parameters

All parameters are optional.

Request Examples

curl https://api.ayra.ai/v1/conversations \
  -H "Authorization: Bearer sk_live_abc123xyz789"

curl "https://api.ayra.ai/v1/conversations?agent_id=agent_abc123&start_date=2025-01-01T00:00:00Z&end_date=2025-01-31T23:59:59Z" \
  -H "Authorization: Bearer sk_live_abc123xyz789"

curl "https://api.ayra.ai/v1/conversations?search=refund&status=completed" \
  -H "Authorization: Bearer sk_live_abc123xyz789"

curl "https://api.ayra.ai/v1/conversations?sentiment=negative&has_transcript=true" \
  -H "Authorization: Bearer sk_live_abc123xyz789"

JavaScript Example

const axios = require('axios');

async function getConversations(options = {}) {
  const params = new URLSearchParams({
    page: options.page || 1,
    per_page: options.per_page || 25,
    ...(options.agent_id && { agent_id: options.agent_id }),
    ...(options.status && { status: options.status }),
    ...(options.sentiment && { sentiment: options.sentiment }),
    ...(options.start_date && { start_date: options.start_date }),
    ...(options.end_date && { end_date: options.end_date }),
    ...(options.search && { search: options.search }),
    ...(options.sort_by && { sort_by: options.sort_by }),
    ...(options.sort_order && { sort_order: options.sort_order })
  });

  try {
    const response = await axios.get(
      `https://api.ayra.ai/v1/conversations?${params}`,
      {
        headers: {
          'Authorization': 'Bearer sk_live_abc123xyz789'
        }
      }
    );
    
    console.log(`Found ${response.data.meta.total} conversations`);
    return response.data;
  } catch (error) {
    console.error('Error fetching conversations:', error.response.data);
    throw error;
  }
}

// Example: Get negative sentiment conversations from last 7 days
const sevenDaysAgo = new Date();
sevenDaysAgo.setDate(sevenDaysAgo.getDate() - 7);

getConversations({
  sentiment: 'negative',
  start_date: sevenDaysAgo.toISOString(),
  status: 'completed',
  sort_by: 'start_time',
  sort_order: 'desc'
});

Python Example

import requests
from datetime import datetime, timedelta

def get_conversations(page=1, per_page=25, **filters):
    url = 'https://api.ayra.ai/v1/conversations'
    headers = {
        'Authorization': 'Bearer sk_live_abc123xyz789'
    }
    
    params = {
        'page': page,
        'per_page': per_page,
        **filters
    }
    
    response = requests.get(url, headers=headers, params=params)
    
    if response.status_code == 200:
        data = response.json()
        print(f"Found {data['meta']['total']} conversations")
        return data
    else:
        print('Error:', response.json())
        raise Exception(f'Failed to get conversations: {response.status_code}')

# Example: Get conversations with recordings from specific agent
seven_days_ago = (datetime.now() - timedelta(days=7)).isoformat()

conversations = get_conversations(
    agent_id='agent_abc123',
    start_date=seven_days_ago,
    has_recording=True,
    status='completed',
    sort_by='duration',
    sort_order='desc'
)

# Process conversations
for conv in conversations['data']:
    print(f"Conversation {conv['id']}: {conv['duration']}s, Sentiment: {conv['sentiment']}")

Response

Success Response (200 OK):

{
  "data": [
    {
      "id": "conv_abc123xyz789",
      "agent_id": "agent_abc123",
      "agent_name": "Customer Support Agent",
      "caller_number": "+15551234567",
      "status": "completed",
      "start_time": "2025-01-15T14:30:00Z",
      "end_time": "2025-01-15T14:35:23Z",
      "duration": 323,
      "sentiment": "positive",
      "outcome": "issue_resolved",
      "topics": ["billing", "refund", "account"],
      "has_recording": true,
      "has_transcript": true,
      "summary": "Customer called regarding a billing issue...",
      "created_at": "2025-01-15T14:30:00Z"
    }
  ],
  "meta": {
    "total": 1247,
    "page": 1,
    "per_page": 25,
    "total_pages": 50,
    "request_id": "req_conversations_list_123",
    "timestamp": "2025-01-15T15:00:00Z"
  },
  "links": {
    "first": "https://api.ayra.ai/v1/conversations?page=1",
    "prev": null,
    "next": "https://api.ayra.ai/v1/conversations?page=2",
    "last": "https://api.ayra.ai/v1/conversations?page=50"
  }
}

Error Responses

{
  "error": {
    "type": "invalid_request",
    "message": "Invalid date format for 'start_date'. Use ISO 8601 format.",
    "code": "invalid_date_format",
    "field": "start_date"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "Invalid value for 'sentiment'. Must be 'positive', 'neutral', or 'negative'.",
    "code": "invalid_parameter",
    "field": "sentiment",
    "valid_values": ["positive", "neutral", "negative"]
  }
}

Advanced Filtering Examples

// Conversations over 10 minutes with negative sentiment
getConversations({
  sentiment: 'negative',
  min_duration: 600,
  status: 'completed',
  sort_by: 'duration',
  sort_order: 'desc'
});

from datetime import datetime, timedelta

def export_monthly_conversations(year, month):
    # Calculate date range
    start_date = datetime(year, month, 1)
    if month == 12:
        end_date = datetime(year + 1, 1, 1) - timedelta(seconds=1)
    else:
        end_date = datetime(year, month + 1, 1) - timedelta(seconds=1)
    
    all_conversations = []
    page = 1
    
    while True:
        response = get_conversations(
            page=page,
            per_page=100,
            start_date=start_date.isoformat(),
            end_date=end_date.isoformat(),
            status='completed'
        )
        
        all_conversations.extend(response['data'])
        
        if page >= response['meta']['total_pages']:
            break
        
        page += 1
    
    return all_conversations

# Export all conversations from January 2025
conversations = export_monthly_conversations(2025, 1)
print(f"Exported {len(conversations)} conversations")

Notes

• •Conversations are cached for 60 seconds for performance. Very recent calls might not appear immediately.
• •Search queries are full-text indexed and support partial matching.
• •Date filters use conversation start time, not end time.
• •Maximum per_page is 100. Larger values are automatically capped.
• •In-progress conversations return partial data that updates as the call continues.