Skip to main content
GET
/
calls
List Calls
curl --request GET \
  --url https://api.example.com/calls
{
  "calls": [
    {
      "id": "<string>",
      "trunk_id": "<string>",
      "from": "<string>",
      "to": "<string>",
      "status": "<string>",
      "duration_seconds": 123,
      "start_time": "<string>",
      "end_time": "<string>",
      "carrier_lag_ms": 123,
      "ai_latency_ms": 123,
      "gateway_processing_ms": 123
    }
  ],
  "pagination": {
    "limit": 123,
    "offset": 123,
    "total": 123
  }
}

​
Overview

Retrieve call history with detailed metrics and filtering.

​
Request

​
limit
integer
default:"20"
Maximum calls to return (1-100)
​
offset
integer
default:"0"
Number of calls to skip for pagination
​
trunk_id
string
Filter by trunk ID
​
status
string
Filter by status: connected, failed, disconnected
​
start_date
string
ISO 8601 date to start from
​
end_date
string
ISO 8601 date to end at

​
Example Request

curl -X GET "https://api.telepathvoice.com/v1/calls?limit=10&status=connected&trunk_id=conn_abc123xyz" \
  -H "Authorization: Bearer sk_live_abc123def456..." \
  -H "Content-Type: application/json"

​
Python Example

import requests
from datetime import datetime, timedelta

API_KEY = "sk_live_abc123def456..."
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Get calls from past 24 hours
yesterday = (datetime.now() - timedelta(days=1)).isoformat()

response = requests.get(
    "https://api.telepathvoice.com/v1/calls",
    headers=headers,
    params={
        "limit": 20,
        "status": "connected",
        "start_date": yesterday
    }
)

calls = response.json()

​
Response

​
calls
array
Array of call objects
​
id
string
Unique call identifier
​
trunk_id
string
Which trunk handled this call
​
from
string
Caller’s phone number
​
to
string
Destination number
​
status
string
Call status: connected, failed, disconnected
​
duration_seconds
integer
Total call duration
​
start_time
string
ISO 8601 call start time
​
end_time
string
ISO 8601 call end time
​
carrier_lag_ms
integer
Carrier delay in milliseconds
​
ai_latency_ms
integer
AI response latency in milliseconds
​
gateway_processing_ms
integer
Telepath processing time in milliseconds
​
pagination
object
​
limit
integer
Items per page
​
offset
integer
Current offset
​
total
integer
Total calls available

​
Example Response

{
  "calls": [
    {
      "id": "call_abc123xyz",
      "trunk_id": "conn_abc123xyz",
      "from": "+1-555-123-4567",
      "to": "+1-555-987-6543",
      "status": "connected",
      "duration_seconds": 342,
      "start_time": "2024-03-05T10:30:00Z",
      "end_time": "2024-03-05T10:36:42Z",
      "carrier_lag_ms": 85,
      "ai_latency_ms": 215,
      "gateway_processing_ms": 22
    },
    {
      "id": "call_def456abc",
      "trunk_id": "conn_abc123xyz",
      "from": "+1-555-234-5678",
      "to": "+1-555-987-6543",
      "status": "connected",
      "duration_seconds": 156,
      "start_time": "2024-03-05T11:15:30Z",
      "end_time": "2024-03-05T11:18:06Z",
      "carrier_lag_ms": 92,
      "ai_latency_ms": 198,
      "gateway_processing_ms": 19
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 1523
  }
}

​
Usage Examples

​
Get Failed Calls

def get_failed_calls(api_key, hours=24):
    """Get calls that failed in the last N hours"""
    from datetime import datetime, timedelta

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    start_date = (datetime.now() - timedelta(hours=hours)).isoformat()

    response = requests.get(
        "https://api.telepathvoice.com/v1/calls",
        headers=headers,
        params={
            "status": "failed",
            "start_date": start_date
        }
    )

    return response.json()['calls']

​
Calculate Average Latency

def get_average_latency(api_key, trunk_id):
    """Calculate average latency for a trunk"""
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    response = requests.get(
        "https://api.telepathvoice.com/v1/calls",
        headers=headers,
        params={
            "trunk_id": trunk_id,
            "status": "connected",
            "limit": 100
        }
    )

    calls = response.json()['calls']

    if not calls:
        return None

    total_latency = sum(
        call['carrier_lag_ms'] +
        call['ai_latency_ms'] +
        call['gateway_processing_ms']
        for call in calls
    )

    return total_latency / len(calls)

​
Daily Report

def generate_daily_report(api_key):
    """Generate daily statistics"""
    from datetime import datetime, timedelta

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    today = datetime.now().date()
    start = f"{today}T00:00:00Z"
    end = f"{today}T23:59:59Z"

    response = requests.get(
        "https://api.telepathvoice.com/v1/calls",
        headers=headers,
        params={
            "start_date": start,
            "end_date": end,
            "limit": 1000
        }
    )

    calls = response.json()['calls']

    # Calculate statistics
    total_calls = len(calls)
    connected_calls = len([c for c in calls if c['status'] == 'connected'])
    failed_calls = len([c for c in calls if c['status'] == 'failed'])
    total_duration = sum(c['duration_seconds'] for c in calls)
    avg_latency = sum(
        c['ai_latency_ms'] for c in calls
    ) / total_calls if total_calls > 0 else 0

    print(f"Daily Report for {today}")
    print(f"Total Calls: {total_calls}")
    print(f"Connected: {connected_calls} ({connected_calls/total_calls*100:.1f}%)")
    print(f"Failed: {failed_calls} ({failed_calls/total_calls*100:.1f}%)")
    print(f"Total Duration: {total_duration/3600:.1f} hours")
    print(f"Avg AI Latency: {avg_latency:.0f}ms")

​
See Also