Skip to main content
Telepath

GET Get Call Details

Get detailed information about a specific call.

endpoint 
GET https://api.telepathvoice.com/v1/calls/{id}

Overview

Retrieve comprehensive details about a specific call, including per-turn metrics, media quality statistics, and the raw SIP trace. Use this endpoint to diagnose issues with individual calls.

Request

Path Parameters

id string required The unique call identifier (e.g., call_abc123xyz).

Example Request

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

Python Example

python 
import requests

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

headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.get(
    f"https://api.telepathvoice.com/v1/calls/{CALL_ID}",
    headers=headers
)
response.raise_for_status()
call = response.json()
print(f"Call duration: {call['duration_seconds']}s")
print(f"Turns: {len(call['turns'])}")

Response

Response Fields

id string Unique call identifier.
trunk_id string The trunk that handled this call.
from string Caller's phone number in E.164 format.
to string Called number in E.164 format.
status string Final call status: connected, failed, or disconnected.
duration_seconds integer Total call duration in seconds.
start_time string ISO 8601 timestamp when the call started.
end_time string ISO 8601 timestamp when the call ended.
disconnect_reason string Human-readable reason for call termination (e.g., "normal_clearing", "caller_hangup").
metrics object Detailed performance metrics for this call.
metrics.carrier_lag_ms integer Average carrier-added latency in milliseconds.
metrics.ai_latency_ms integer Average AI model response time in milliseconds.
metrics.gateway_processing_ms integer Average Telepath gateway processing overhead in milliseconds.
metrics.packet_loss_percent number Percentage of RTP packets lost during the call.
metrics.jitter_ms integer Average RTP jitter in milliseconds.
metrics.codec_used string Audio codec negotiated for this call (e.g., "G711u", "G722").
turns array Per-turn breakdown of the conversation.
turns[].turn_number integer Sequential turn index (1-based).
turns[].speaker string Who spoke: "caller" or "agent".
turns[].duration_ms integer Duration of this speech turn in milliseconds.
turns[].processing_time_ms integer Time from end of caller speech to start of agent response, in milliseconds.
sip_trace string Raw SIP signalling trace for this call (INVITE, 100 Trying, 200 OK, BYE, etc.).

Example Response

json 
{
  "id": "call_abc123xyz",
  "trunk_id": "conn_abc123xyz",
  "from": "+14155550100",
  "to": "+18005550199",
  "status": "disconnected",
  "duration_seconds": 142,
  "start_time": "2024-03-10T14:00:00Z",
  "end_time": "2024-03-10T14:02:22Z",
  "disconnect_reason": "caller_hangup",
  "metrics": {
    "carrier_lag_ms": 45,
    "ai_latency_ms": 130,
    "gateway_processing_ms": 12,
    "packet_loss_percent": 0.2,
    "jitter_ms": 4,
    "codec_used": "G722"
  },
  "turns": [
    {
      "turn_number": 1,
      "speaker": "agent",
      "duration_ms": 3200,
      "processing_time_ms": 0
    },
    {
      "turn_number": 2,
      "speaker": "caller",
      "duration_ms": 4500,
      "processing_time_ms": 0
    },
    {
      "turn_number": 3,
      "speaker": "agent",
      "duration_ms": 5100,
      "processing_time_ms": 187
    }
  ],
  "sip_trace": "INVITE sip:[email protected] SIP/2.0\r\nVia: SIP/2.0/UDP carrier.example.com;branch=z9hG4bK776asdhds\r\n...\r\nSIP/2.0 100 Trying\r\nSIP/2.0 200 OK\r\n..."
}

Error Responses

Call Not Found (404)

json 
{
  "error": {
    "code": "not_found",
    "message": "Call 'call_abc123xyz' not found",
    "status": 404
  }
}

Usage Examples

Analyze Failed Call

python 
def analyze_failed_call(api_key, call_id):
    headers = {"Authorization": f"Bearer {api_key}"}
    r = requests.get(
        f"https://api.telepathvoice.com/v1/calls/{call_id}",
        headers=headers
    )
    r.raise_for_status()
    call = r.json()

    print(f"Call ID:          {call['id']}")
    print(f"Status:           {call['status']}")
    print(f"Disconnect:       {call['disconnect_reason']}")
    print(f"Carrier lag:      {call['metrics']['carrier_lag_ms']} ms")
    print(f"AI latency:       {call['metrics']['ai_latency_ms']} ms")
    print(f"Packet loss:      {call['metrics']['packet_loss_percent']}%")
    print(f"Jitter:           {call['metrics']['jitter_ms']} ms")
    if call["metrics"]["packet_loss_percent"] > 2:
        print("WARNING: High packet loss — likely a carrier network issue.")

Compare Latency Breakdown

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

m = call["metrics"]
total = m["carrier_lag_ms"] + m["ai_latency_ms"] + m["gateway_processing_ms"]
print(f"Latency breakdown:")
print(f"  Carrier:  {m['carrier_lag_ms']:4d} ms  ({m['carrier_lag_ms']/total*100:.0f}%)")
print(f"  AI model: {m['ai_latency_ms']:4d} ms  ({m['ai_latency_ms']/total*100:.0f}%)")
print(f"  Gateway:  {m['gateway_processing_ms']:4d} ms  ({m['gateway_processing_ms']/total*100:.0f}%)")
print(f"  Total:    {total:4d} ms")

Generate Diagnostic Report

python 
import json

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

report = {
    "call_id": call["id"],
    "duration_s": call["duration_seconds"],
    "status": call["status"],
    "turns": len(call["turns"]),
    "avg_processing_ms": (
        sum(t["processing_time_ms"] for t in call["turns"] if t["speaker"] == "agent")
        / max(1, sum(1 for t in call["turns"] if t["speaker"] == "agent"))
    ),
    "metrics": call["metrics"]
}

print(json.dumps(report, indent=2))

See Also