Skip to main content
Telepath

GET Analytics Overview

Get aggregated analytics and statistics.

endpoint 
GET https://api.telepathvoice.com/v1/analytics/overview

Overview

Retrieve aggregated analytics and statistics across all calls for a given time period. The response includes volume summaries, latency percentiles, media quality metrics, per-provider and per-trunk breakdowns, and a timeseries for trending.

Request

Query Parameters

start_date string Start of the analytics period. ISO 8601 format. Default: 7 days ago.
end_date string End of the analytics period. ISO 8601 format. Default: today.
trunk_id string Filter analytics to a specific trunk. Omit to aggregate all trunks.
granularity string Timeseries granularity: daily or hourly. Default: daily.

Example Request

bash 
curl -X GET "https://api.telepathvoice.com/v1/analytics/overview?start_date=2024-03-01T00:00:00Z&end_date=2024-03-10T23:59:59Z&granularity=daily" \
  -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}"}

# Last 7 days
now = datetime.now(timezone.utc)
week_ago = now - timedelta(days=7)

params = {
    "start_date": week_ago.isoformat(),
    "end_date": now.isoformat(),
    "granularity": "daily"
}

response = requests.get(f"{BASE_URL}/analytics/overview", headers=headers, params=params)
data = response.json()
print(f"Period: {data['period']['start_date']} → {data['period']['end_date']}")
print(f"Total calls:   {data['summary']['total_calls']}")
print(f"Success rate:  {data['summary']['success_rate']}%")
print(f"Avg latency:   {data['performance']['avg_total_latency_ms']} ms")

Response

Response Fields

period object The date range covered by this response.
period.start_date string Start of the period (ISO 8601).
period.end_date string End of the period (ISO 8601).
summary object High-level call volume and outcome summary.
summary.total_calls integer Total number of calls in the period.
summary.connected_calls integer Calls that connected successfully.
summary.failed_calls integer Calls that failed to connect.
summary.success_rate number Percentage of calls that connected (0–100).
summary.total_duration_seconds integer Total talk time across all calls in seconds.
summary.avg_duration_seconds number Average call duration in seconds.
performance object Latency statistics across all calls.
performance.avg_carrier_lag_ms integer Average carrier-added latency in milliseconds.
performance.avg_ai_latency_ms integer Average AI model response time in milliseconds.
performance.avg_gateway_processing_ms integer Average Telepath gateway overhead in milliseconds.
performance.avg_total_latency_ms integer Average total end-to-end latency in milliseconds.
performance.p95_latency_ms integer 95th percentile total latency in milliseconds.
performance.p99_latency_ms integer 99th percentile total latency in milliseconds.
quality object Audio quality metrics.
quality.avg_packet_loss_percent number Average RTP packet loss percentage.
quality.avg_jitter_ms integer Average RTP jitter in milliseconds.
quality.codec_distribution object Percentage of calls using each codec (e.g., {"G711": 62.5, "G722": 37.5}).
by_provider array Per-AI-provider breakdown.
by_provider[].provider string Provider name: openai, elevenlabs, or custom.
by_provider[].call_count integer Number of calls handled by this provider.
by_provider[].success_rate number Success rate for this provider (0–100).
by_provider[].avg_latency_ms integer Average total latency for this provider.
by_trunk array Per-trunk breakdown.
by_trunk[].trunk_id string Trunk identifier.
by_trunk[].trunk_name string Friendly name of the trunk.
by_trunk[].call_count integer Calls through this trunk in the period.
by_trunk[].success_rate number Success rate for this trunk (0–100).
timeseries array Time-ordered data points at the requested granularity.
timeseries[].timestamp string ISO 8601 timestamp for this data point.
timeseries[].calls integer Number of calls in this interval.
timeseries[].avg_latency_ms integer Average total latency in this interval.
timeseries[].success_rate number Success rate in this interval (0–100).

Example Response

json 
{
  "period": {
    "start_date": "2024-03-01T00:00:00Z",
    "end_date": "2024-03-10T23:59:59Z"
  },
  "summary": {
    "total_calls": 4821,
    "connected_calls": 4762,
    "failed_calls": 59,
    "success_rate": 98.8,
    "total_duration_seconds": 684570,
    "avg_duration_seconds": 143.7
  },
  "performance": {
    "avg_carrier_lag_ms": 42,
    "avg_ai_latency_ms": 127,
    "avg_gateway_processing_ms": 11,
    "avg_total_latency_ms": 180,
    "p95_latency_ms": 290,
    "p99_latency_ms": 430
  },
  "quality": {
    "avg_packet_loss_percent": 0.18,
    "avg_jitter_ms": 3,
    "codec_distribution": {
      "G711": 62.5,
      "G722": 37.5
    }
  },
  "by_provider": [
    {
      "provider": "openai",
      "call_count": 3210,
      "success_rate": 99.1,
      "avg_latency_ms": 172
    },
    {
      "provider": "elevenlabs",
      "call_count": 1611,
      "success_rate": 98.2,
      "avg_latency_ms": 195
    }
  ],
  "by_trunk": [
    {
      "trunk_id": "conn_abc123xyz",
      "trunk_name": "Production OpenAI Agent",
      "call_count": 3210,
      "success_rate": 99.1
    },
    {
      "trunk_id": "conn_def456uvw",
      "trunk_name": "Staging ElevenLabs Agent",
      "call_count": 1611,
      "success_rate": 98.2
    }
  ],
  "timeseries": [
    {
      "timestamp": "2024-03-01T00:00:00Z",
      "calls": 482,
      "avg_latency_ms": 178,
      "success_rate": 99.0
    },
    {
      "timestamp": "2024-03-02T00:00:00Z",
      "calls": 491,
      "avg_latency_ms": 181,
      "success_rate": 98.8
    },
    {
      "timestamp": "2024-03-03T00:00:00Z",
      "calls": 467,
      "avg_latency_ms": 175,
      "success_rate": 99.2
    }
  ]
}

Usage Examples

Daily Performance Report

python 
from datetime import date, timedelta
import requests

API_KEY = "sk_live_abc123def456..."
headers = {"Authorization": f"Bearer {API_KEY}"}

today = date.today()
week_ago = today - timedelta(days=7)

r = requests.get(
    "https://api.telepathvoice.com/v1/analytics/overview",
    headers=headers,
    params={
        "start_date": f"{week_ago}T00:00:00Z",
        "end_date": f"{today}T23:59:59Z"
    }
)
data = r.json()
s = data["summary"]
p = data["performance"]

print("=== Weekly Performance Report ===")
print(f"Total calls:     {s['total_calls']:,}")
print(f"Success rate:    {s['success_rate']}%")
print(f"Avg duration:    {s['avg_duration_seconds']:.0f}s")
print(f"Avg latency:     {p['avg_total_latency_ms']} ms")
print(f"p95 latency:     {p['p95_latency_ms']} ms")
print(f"p99 latency:     {p['p99_latency_ms']} ms")

Compare Provider Performance

python 
r = requests.get(
    "https://api.telepathvoice.com/v1/analytics/overview",
    headers=headers
)
data = r.json()

print("Provider comparison:")
print(f"{'Provider':<12} {'Calls':>8} {'Success%':>10} {'Latency ms':>12}")
print("-" * 46)
for p in data["by_provider"]:
    print(
        f"{p['provider']:<12} {p['call_count']:>8,} "
        f"{p['success_rate']:>9.1f}% {p['avg_latency_ms']:>11} ms"
    )

Monitor Trend Over Time

python 
r = requests.get(
    "https://api.telepathvoice.com/v1/analytics/overview",
    headers=headers,
    params={"granularity": "daily"}
)
timeseries = r.json()["timeseries"]

print("Daily trend:")
for point in timeseries:
    day = point["timestamp"][:10]
    bar = "#" * (point["calls"] // 50)
    print(f"{day}  {point['calls']:4d} calls  {bar}")

Detect Anomalies

python 
r = requests.get(
    "https://api.telepathvoice.com/v1/analytics/overview",
    headers=headers,
    params={"granularity": "hourly"}
)
data = r.json()
avg_latency = data["performance"]["avg_total_latency_ms"]

print("Anomaly detection (latency spikes):")
for point in data["timeseries"]:
    if point["avg_latency_ms"] > avg_latency * 1.5:
        print(
            f"  SPIKE at {point['timestamp']}: "
            f"{point['avg_latency_ms']} ms "
            f"({point['avg_latency_ms'] / avg_latency:.1f}x average)"
        )
    if point["success_rate"] < 95:
        print(
            f"  LOW SUCCESS at {point['timestamp']}: "
            f"{point['success_rate']}% ({point['calls']} calls)"
        )

See Also