Skip to main content
Telepath

GET List Calls

Get call history and logs.

endpoint 
GET https://api.telepathvoice.com/v1/calls

Overview

Retrieve call history with detailed metrics and filtering. Each call record includes timing, status, and per-segment latency breakdowns (carrier lag, AI processing, gateway overhead).

Request

Query Parameters

limit integer Maximum number of calls to return. Range: 1–100. Default: 20.
offset integer Number of calls to skip for pagination. Default: 0.
trunk_id string Filter calls by trunk ID (e.g., conn_abc123xyz).
status string Filter by call status: connected, failed, or disconnected.
start_date string Filter calls on or after this date. ISO 8601 format (e.g., 2024-03-01T00:00:00Z).
end_date string Filter calls on or before this date. ISO 8601 format.

Example Request

bash 
curl -X GET "https://api.telepathvoice.com/v1/calls?limit=20&trunk_id=conn_abc123xyz&status=failed&start_date=2024-03-01T00:00:00Z" \
  -H "Authorization: Bearer sk_live_abc123def456..." \
  -H "Content-Type: application/json"

Python Example

python 
import requests
from datetime import datetime, timedelta, timezone

API_KEY = "sk_live_abc123def456..."
BASE_URL = "https://api.telepathvoice.com/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Fetch calls from the past 24 hours
now = datetime.now(timezone.utc)
yesterday = now - timedelta(hours=24)

params = {
    "limit": 100,
    "start_date": yesterday.isoformat(),
    "end_date": now.isoformat()
}

response = requests.get(f"{BASE_URL}/calls", headers=headers, params=params)
data = response.json()
print(f"Calls in last 24h: {data['pagination']['total']}")

Response

Response Fields

calls array Array of call records.
calls[].id string Unique call identifier (e.g., call_abc123xyz).
calls[].trunk_id string The trunk that handled this call.
calls[].from string Caller's phone number in E.164 format.
calls[].to string Called number in E.164 format.
calls[].status string Final call status: connected, failed, or disconnected.
calls[].duration_seconds integer Total call duration in seconds.
calls[].start_time string ISO 8601 timestamp when the call started.
calls[].end_time string ISO 8601 timestamp when the call ended.
calls[].carrier_lag_ms integer Average carrier-added latency in milliseconds.
calls[].ai_latency_ms integer Average AI model response time in milliseconds.
calls[].gateway_processing_ms integer Average Telepath gateway processing overhead in milliseconds.
pagination object Pagination metadata: limit, offset, total.

Example Response

json 
{
  "calls": [
    {
      "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",
      "carrier_lag_ms": 45,
      "ai_latency_ms": 130,
      "gateway_processing_ms": 12
    },
    {
      "id": "call_def456uvw",
      "trunk_id": "conn_abc123xyz",
      "from": "+14155550101",
      "to": "+18005550199",
      "status": "failed",
      "duration_seconds": 0,
      "start_time": "2024-03-10T13:55:00Z",
      "end_time": "2024-03-10T13:55:03Z",
      "carrier_lag_ms": 0,
      "ai_latency_ms": 0,
      "gateway_processing_ms": 3
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 2
  }
}

Usage Examples

Get Failed Calls

python 
r = requests.get(
    f"{BASE_URL}/calls",
    headers=headers,
    params={"status": "failed", "limit": 100}
)
failed = r.json()["calls"]
print(f"{len(failed)} failed calls")
for call in failed:
    print(f"  {call['id']}: {call['from']} → {call['to']} at {call['start_time']}")

Calculate Average Latency

python 
r = requests.get(f"{BASE_URL}/calls", headers=headers, params={"limit": 100, "status": "disconnected"})
calls = r.json()["calls"]

if calls:
    avg_carrier = sum(c["carrier_lag_ms"] for c in calls) / len(calls)
    avg_ai      = sum(c["ai_latency_ms"] for c in calls) / len(calls)
    avg_gw      = sum(c["gateway_processing_ms"] for c in calls) / len(calls)
    print(f"Avg carrier lag:   {avg_carrier:.0f} ms")
    print(f"Avg AI latency:    {avg_ai:.0f} ms")
    print(f"Avg gateway proc:  {avg_gw:.0f} ms")
    print(f"Avg total:         {avg_carrier + avg_ai + avg_gw:.0f} ms")

Daily Report

python 
from datetime import date

today = date.today().isoformat()
r = requests.get(
    f"{BASE_URL}/calls",
    headers=headers,
    params={
        "start_date": f"{today}T00:00:00Z",
        "end_date":   f"{today}T23:59:59Z",
        "limit": 100
    }
)
data = r.json()
calls = data["calls"]
total = data["pagination"]["total"]
failed = sum(1 for c in calls if c["status"] == "failed")
print(f"Date: {today}")
print(f"Total calls: {total}")
print(f"Failed:      {failed} ({failed/total*100:.1f}%)" if total else "No calls today.")

See Also