Analytics

The Analytics API provides aggregate metrics, time series data, and distribution histograms for your call operations. All analytics endpoints share a common set of filter parameters.

Common Query Parameters

Every analytics endpoint accepts these optional query parameters:

Parameter	Type	Description
start_date	datetime	Filter calls starting from this timestamp (ISO 8601)
end_date	datetime	Filter calls up to this timestamp (ISO 8601)
agent_id	uuid	Filter to a specific agent

Example:

GET /analytics/overview?start_date=2026-02-01T00:00:00Z&end_date=2026-02-28T23:59:59Z&agent_id=550e8400-...

Overview

GET /analytics/overview

Summary statistics across all calls.

Response

{
  "total_calls": 1250,
  "total_duration": 45230.5,
  "avg_duration": 36.2,
  "completed_calls": 1100,
  "failed_calls": 50
}

Field	Type	Description
total_calls	integer	Total number of calls
total_duration	float	Sum of all call durations (seconds)
avg_duration	float	Average call duration (seconds)
completed_calls	integer	Calls with status completed
failed_calls	integer	Calls with status failed

Call Volume

GET /analytics/call-volume

Daily call count time series.

Response

[
  { "date": "2026-02-01", "count": 45 },
  { "date": "2026-02-02", "count": 52 }
]

Latency

GET /analytics/latency

Average pipeline latencies and a daily trend. Latencies are measured in milliseconds for each pipeline stage: STT, LLM, TTS, and the total end-to-end latency.

Response

{
  "avg_stt_latency_ms": 120.5,
  "avg_llm_latency_ms": 450.2,
  "avg_tts_latency_ms": 85.3,
  "avg_total_latency_ms": 655.0,
  "daily_trend": [
    {
      "date": "2026-02-01",
      "stt_latency_ms": 115.0,
      "llm_latency_ms": 440.0,
      "tts_latency_ms": 80.0,
      "total_latency_ms": 635.0
    }
  ]
}

Cost Overview

GET /analytics/cost-overview

Aggregate cost metrics. If a call has an explicit total_cost recorded, that value is used. Otherwise, cost is estimated from call duration.

Response

{
  "total_spend": 125.50,
  "avg_cost_per_call": 0.10,
  "stt_cost_total": 0.0,
  "llm_cost_total": 0.0,
  "tts_cost_total": 0.0
}

Cost Trend

GET /analytics/cost-trend

Daily total cost time series.

Response

[
  { "date": "2026-02-01", "total_cost": 4.25 },
  { "date": "2026-02-02", "total_cost": 5.10 }
]

Cost by Agent

GET /analytics/cost-by-agent

Total cost grouped by agent, sorted by highest cost first.

Response

[
  {
    "agent_id": "550e8400-...",
    "agent_name": "Support Agent",
    "total_cost": 75.00
  },
  {
    "agent_id": "660e8400-...",
    "agent_name": "Sales Agent",
    "total_cost": 50.50
  }
]

Duration Distribution

GET /analytics/duration-distribution

Histogram of call durations in predefined second-based buckets.

Response

{
  "buckets": [
    { "bucket": "0-30", "count": 200 },
    { "bucket": "30-60", "count": 350 },
    { "bucket": "60-120", "count": 400 },
    { "bucket": "120-300", "count": 250 },
    { "bucket": "300+", "count": 50 }
  ]
}

Latency Distribution

GET /analytics/latency-distribution

Histogram of total end-to-end latency in millisecond-based buckets.

Response

{
  "buckets": [
    { "bucket": "0-500", "count": 100 },
    { "bucket": "500-1000", "count": 500 },
    { "bucket": "1000-2000", "count": 400 },
    { "bucket": "2000-3000", "count": 150 },
    { "bucket": "3000+", "count": 50 }
  ]
}

Conversation Turns

GET /analytics/conversation-turns

Average number of conversation turns (back-and-forth exchanges) per call, with a daily trend.

Response

{
  "avg_turns": 8.5,
  "daily_trend": [
    { "date": "2026-02-01", "avg_turns": 7.2 },
    { "date": "2026-02-02", "avg_turns": 9.1 }
  ]
}

Barge-In

GET /analytics/barge-in

Barge-in rate (percentage of calls where the caller interrupted the agent at least once) and daily trend.

Response

{
  "barge_in_rate": 0.35,
  "daily_trend": [
    { "date": "2026-02-01", "barge_in_rate": 0.32 },
    { "date": "2026-02-02", "barge_in_rate": 0.38 }
  ]
}

The rate is a decimal between 0 and 1 (e.g. 0.35 = 35% of calls had barge-in).

Provider Errors

GET /analytics/provider-errors

Error count and error rate per provider.

Response

[
  {
    "provider_name": "deepgram",
    "error_count": 3,
    "total_calls": 500,
    "error_rate": 0.006
  }
]

Peak Hours

GET /analytics/peak-hours

Call count grouped by day of the week and hour. Uses ISO weekday convention (0 = Monday, 6 = Sunday).

Response

[
  { "day_of_week": 0, "hour": 9, "count": 25 },
  { "day_of_week": 0, "hour": 10, "count": 42 },
  { "day_of_week": 1, "hour": 14, "count": 38 }
]

Outcomes

GET /analytics/outcomes

Call count grouped by outcome. Falls back to status-based grouping for calls without an explicit outcome field.

Response

[
  { "outcome": "completed", "count": 800 },
  { "outcome": "voicemail", "count": 150 },
  { "outcome": "caller_hangup", "count": 100 },
  { "outcome": "failed", "count": 50 }
]

Agent Comparison

GET /analytics/agent-comparison

Side-by-side performance metrics for multiple agents. Useful for comparing agent configurations.

Additional Query Parameters

Parameter	Type	Description
agent_ids	string	Comma-separated agent UUIDs to compare

Note: This endpoint uses agent_ids (comma-separated) instead of the standard agent_id filter.

Response

[
  {
    "agent_id": "550e8400-...",
    "agent_name": "Support Agent",
    "total_calls": 500,
    "avg_duration": 45.2,
    "completion_rate": 0.92,
    "avg_stt_latency_ms": 115.0,
    "avg_llm_latency_ms": 420.0,
    "avg_tts_latency_ms": 80.0,
    "avg_total_latency_ms": 615.0,
    "avg_cost": 0.12,
    "barge_in_rate": 0.30,
    "avg_turns": 8.5,
    "error_count": 5
  }
]

Field	Type	Description
agent_id	uuid	Agent ID
agent_name	string	Agent display name
total_calls	integer	Number of calls handled
avg_duration	float	Average call duration (seconds)
completion_rate	float	Ratio of completed calls to total calls
avg_stt_latency_ms	float	Average STT latency (ms)
avg_llm_latency_ms	float	Average LLM latency (ms)
avg_tts_latency_ms	float	Average TTS latency (ms)
avg_total_latency_ms	float	Average total pipeline latency (ms)
avg_cost	float	Average cost per call
barge_in_rate	float	Fraction of calls with barge-in
avg_turns	float	Average conversation turns
error_count	integer	Number of calls with errors

STT Events

GET /analytics/stt-events

Per-call STT connection lifecycle events. Tracks when STT connections are opened, closed, rejected, or time out.

Query Parameters

Parameter	Type	Description
call_sid	string	Filter by Twilio Call SID
event_type	string	Filter by event type (see below)
start_date	datetime	Filter events from this timestamp
end_date	datetime	Filter events up to this timestamp
limit	integer	Max results (default 100, max 500)

Event Types

Type	Description
connection_opened	STT WebSocket connection established
connection_closed	STT connection closed normally
connection_rejected	STT connection rejected by provider
timeout	STT connection timed out
error	STT connection error
utterance_end_fallback	Fell back to utterance-end detection

Response

[
  {
    "id": "...",
    "call_sid": "CA1234567890abcdef",
    "event_type": "connection_opened",
    "provider_name": "deepgram",
    "model": "nova-2",
    "detail": { "language": "en" },
    "created_at": "2026-03-01T14:30:00Z"
  }
]

STT Events Summary

GET /analytics/stt-events/summary

Aggregate STT event statistics over a time range. Useful for monitoring STT connection health.

Query Parameters

Parameter	Type	Description
start_date	datetime	Filter events from this timestamp
end_date	datetime	Filter events up to this timestamp

Response

{
  "total_events": 2500,
  "connections_opened": 1200,
  "connections_closed": 1180,
  "connections_rejected": 15,
  "timeouts": 5,
  "errors": 3,
  "utterance_end_fallbacks": 42,
  "avg_connection_duration_s": 35.2,
  "rejection_rate": 0.012,
  "timeout_rate": 0.004
}

Field	Type	Description
total_events	integer	Total STT events recorded
connections_opened	integer	Successful connection opens
connections_closed	integer	Normal connection closes
connections_rejected	integer	Connections rejected by provider
timeouts	integer	Connection timeouts
errors	integer	Connection errors
utterance_end_fallbacks	integer	Fallbacks to utterance-end detection
avg_connection_duration_s	float | null	Average connection lifespan (seconds)
rejection_rate	float	Rejected / (opened + rejected)
timeout_rate	float	Timeouts / opened