Skip to main content
GET
/
calls
/
{id}
Get Call Details
curl --request GET \
  --url https://api.example.com/calls/{id}
{
  "id": "<string>",
  "trunk_id": "<string>",
  "from": "<string>",
  "to": "<string>",
  "status": "<string>",
  "duration_seconds": 123,
  "start_time": "<string>",
  "end_time": "<string>",
  "disconnect_reason": "<string>",
  "metrics": {
    "carrier_lag_ms": 123,
    "ai_latency_ms": 123,
    "gateway_processing_ms": 123,
    "packet_loss_percent": 123,
    "jitter_ms": 123,
    "codec_used": "<string>"
  },
  "turns": [
    {
      "turn_number": 123,
      "speaker": "<string>",
      "duration_ms": 123,
      "processing_time_ms": 123
    }
  ],
  "sip_trace": "<string>"
}

​
Overview

Retrieve comprehensive details about a specific call, including metrics and SIP trace.

​
Request

​
id
string
required
The call ID (e.g., call_abc123xyz)

​
Example Request

curl -X GET https://api.telepathvoice.com/v1/calls/call_abc123xyz \
  -H "Authorization: Bearer sk_live_abc123def456..." \
  -H "Content-Type: application/json"

​
Python Example

import requests

API_KEY = "sk_live_abc123def456..."
CALL_ID = "call_abc123xyz"

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

response = requests.get(
    f"https://api.telepathvoice.com/v1/calls/{CALL_ID}",
    headers=headers
)

call_details = response.json()

​
Response

​
id
string
Call identifier
​
trunk_id
string
Which trunk handled this call
​
from
string
Caller’s phone number
​
to
string
Destination number
​
status
string
Call status
​
duration_seconds
integer
Total call duration
​
start_time
string
ISO 8601 start timestamp
​
end_time
string
ISO 8601 end timestamp
​
disconnect_reason
string
Why call ended (if available)
​
metrics
object
Performance metrics
​
carrier_lag_ms
integer
Delay from carrier to Telepath
​
ai_latency_ms
integer
Average AI response time
​
gateway_processing_ms
integer
Telepath processing time
​
packet_loss_percent
number
Percentage of lost packets
​
jitter_ms
integer
Audio timing variance
​
codec_used
string
Audio codec (G.711, G.722)
​
turns
array
Turn-by-turn conversation metrics
​
turn_number
integer
Sequential turn number
​
speaker
string
Who spoke (caller, agent)
​
duration_ms
integer
How long this turn lasted
​
processing_time_ms
integer
Time to process this turn
​
sip_trace
string
Complete SIP signaling log

​
Example Response

{
  "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",
  "disconnect_reason": "normal_disconnect",
  "metrics": {
    "carrier_lag_ms": 85,
    "ai_latency_ms": 215,
    "gateway_processing_ms": 22,
    "packet_loss_percent": 0.2,
    "jitter_ms": 12,
    "codec_used": "G.722"
  },
  "turns": [
    {
      "turn_number": 1,
      "speaker": "caller",
      "duration_ms": 2340,
      "processing_time_ms": 0
    },
    {
      "turn_number": 2,
      "speaker": "agent",
      "duration_ms": 3210,
      "processing_time_ms": 285
    }
  ],
  "sip_trace": "SIP/2.0 100 Trying\nVia: SIP/2.0/TLS..."
}

​
Error Responses

​
Call Not Found

{
  "error": {
    "code": "CALL_NOT_FOUND",
    "message": "Call 'call_abc123xyz' not found"
  }
}
Status Code: 404

​
Usage Examples

​
Analyze Failed Call

def analyze_failed_call(api_key, call_id):
    """Diagnose why a call failed"""
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    response = requests.get(
        f"https://api.telepathvoice.com/v1/calls/{call_id}",
        headers=headers
    )

    call = response.json()

    print(f"Call {call['id']} Status: {call['status']}")
    print(f"Disconnect Reason: {call.get('disconnect_reason', 'Unknown')}")

    # Check metrics
    metrics = call['metrics']
    print(f"\nMetrics:")
    print(f"  Carrier Lag: {metrics['carrier_lag_ms']}ms")
    print(f"  AI Latency: {metrics['ai_latency_ms']}ms")
    print(f"  Packet Loss: {metrics['packet_loss_percent']}%")

    # Check SIP trace for errors
    if "500" in call['sip_trace'] or "403" in call['sip_trace']:
        print(f"\nServer Error detected in SIP trace")
        print(f"Check AI provider configuration")

    if metrics['packet_loss_percent'] > 5:
        print(f"\nHigh packet loss - check network connection")

​
Compare Latency Breakdown

def compare_latencies(api_key, call_ids):
    """Compare latency components across calls"""
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }

    for call_id in call_ids:
        response = requests.get(
            f"https://api.telepathvoice.com/v1/calls/{call_id}",
            headers=headers
        )

        call = response.json()
        metrics = call['metrics']

        carrier = metrics['carrier_lag_ms']
        ai = metrics['ai_latency_ms']
        gateway = metrics['gateway_processing_ms']
        total = carrier + ai + gateway

        print(f"{call['id']}:")
        print(f"  Carrier:   {carrier:4d}ms ({carrier/total*100:5.1f}%)")
        print(f"  AI:        {ai:4d}ms ({ai/total*100:5.1f}%)")
        print(f"  Gateway:   {gateway:4d}ms ({gateway/total*100:5.1f}%)")
        print(f"  Total:     {total:4d}ms")

​
Generate Diagnostic Report

def generate_call_diagnostics(api_key, call_id):
    """Generate comprehensive diagnostic report for support"""
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    response = requests.get(
        f"https://api.telepathvoice.com/v1/calls/{call_id}",
        headers=headers
    )

    call = response.json()

    report = f"""
CALL DIAGNOSTICS REPORT
=======================

Call ID: {call['id']}
Status: {call['status']}
Duration: {call['duration_seconds']}s

TIME
Start: {call['start_time']}
End: {call['end_time']}

PARTICIPANTS
From: {call['from']}
To: {call['to']}

PERFORMANCE METRICS
Carrier Lag: {call['metrics']['carrier_lag_ms']}ms
AI Latency: {call['metrics']['ai_latency_ms']}ms
Gateway Processing: {call['metrics']['gateway_processing_ms']}ms
Packet Loss: {call['metrics']['packet_loss_percent']}%
Jitter: {call['metrics']['jitter_ms']}ms
Codec: {call['metrics']['codec_used']}

CONVERSATION TURNS: {len(call['turns'])}
"""

    for turn in call['turns']:
        report += f"\nTurn {turn['turn_number']}: {turn['speaker']} - {turn['duration_ms']}ms"

    return report

​
See Also