Saltar al contenido principal

Analiticas

La API de Analiticas proporciona metricas agregadas, datos de series temporales e histogramas de distribucion para tus operaciones de llamadas. Todos los endpoints de analiticas comparten un conjunto comun de parametros de filtro.

Parametros de Consulta Comunes​

Cada endpoint de analiticas acepta estos parametros de consulta opcionales:

ParametroTipoDescripcion
start_datedatetimeFiltrar llamadas desde esta marca de tiempo (ISO 8601)
end_datedatetimeFiltrar llamadas hasta esta marca de tiempo (ISO 8601)
agent_iduuidFiltrar por un agente especifico

Ejemplo:

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

Resumen General​

GET /analytics/overview

Estadisticas resumidas de todas las llamadas.

Respuesta​

{
  "total_calls": 1250,
  "total_duration": 45230.5,
  "avg_duration": 36.2,
  "completed_calls": 1100,
  "failed_calls": 50
}
CampoTipoDescripcion
total_callsintegerNumero total de llamadas
total_durationfloatSuma de todas las duraciones de llamadas (segundos)
avg_durationfloatDuracion promedio de llamada (segundos)
completed_callsintegerLlamadas con estado completed
failed_callsintegerLlamadas con estado failed

Volumen de Llamadas​

GET /analytics/call-volume

Serie temporal diaria del conteo de llamadas.

Respuesta​

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

Latencia​

GET /analytics/latency

Latencias promedio del pipeline y tendencia diaria. Las latencias se miden en milisegundos para cada etapa del pipeline: STT, LLM, TTS y la latencia total de extremo a extremo.

Respuesta​

{
  "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
    }
  ]
}

Resumen de Costos​

GET /analytics/cost-overview

Metricas de costos agregadas. Si una llamada tiene un total_cost explicito registrado, se usa ese valor. De lo contrario, el costo se estima a partir de la duracion de la llamada.

Respuesta​

{
  "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
}

Tendencia de Costos​

GET /analytics/cost-trend

Serie temporal diaria del costo total.

Respuesta​

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

Costo por Agente​

GET /analytics/cost-by-agent

Costo total agrupado por agente, ordenado por mayor costo primero.

Respuesta​

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

Distribucion de Duracion​

GET /analytics/duration-distribution

Histograma de duraciones de llamadas en rangos predefinidos en segundos.

Respuesta​

{
  "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 }
  ]
}

Distribucion de Latencia​

GET /analytics/latency-distribution

Histograma de la latencia total de extremo a extremo en rangos basados en milisegundos.

Respuesta​

{
  "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 }
  ]
}

Turnos de Conversacion​

GET /analytics/conversation-turns

Numero promedio de turnos de conversacion (intercambios de ida y vuelta) por llamada, con tendencia diaria.

Respuesta​

{
  "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

Tasa de barge-in (porcentaje de llamadas donde el llamante interrumpio al agente al menos una vez) y tendencia diaria.

Respuesta​

{
  "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 }
  ]
}

La tasa es un decimal entre 0 y 1 (ej. 0.35 = 35% de las llamadas tuvieron barge-in).

Errores de Proveedor​

GET /analytics/provider-errors

Conteo de errores y tasa de error por proveedor.

Respuesta​

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

Horas Pico​

GET /analytics/peak-hours

Conteo de llamadas agrupado por dia de la semana y hora. Usa la convencion ISO de dias de la semana (0 = Lunes, 6 = Domingo).

Respuesta​

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

Resultados​

GET /analytics/outcomes

Conteo de llamadas agrupado por resultado. Recurre a la agrupacion basada en estado para llamadas sin un campo de resultado explicito.

Respuesta​

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

Comparacion de Agentes​

GET /analytics/agent-comparison

Metricas de rendimiento comparativas para multiples agentes. Util para comparar configuraciones de agentes.

Parametros de Consulta Adicionales​

ParametroTipoDescripcion
agent_idsstringUUIDs de agentes separados por comas para comparar

Nota: Este endpoint usa agent_ids (separados por comas) en lugar del filtro estandar agent_id.

Respuesta​

[
  {
    "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
  }
]
CampoTipoDescripcion
agent_iduuidID del agente
agent_namestringNombre visible del agente
total_callsintegerNumero de llamadas atendidas
avg_durationfloatDuracion promedio de llamada (segundos)
completion_ratefloatProporcion de llamadas completadas respecto al total
avg_stt_latency_msfloatLatencia STT promedio (ms)
avg_llm_latency_msfloatLatencia LLM promedio (ms)
avg_tts_latency_msfloatLatencia TTS promedio (ms)
avg_total_latency_msfloatLatencia total promedio del pipeline (ms)
avg_costfloatCosto promedio por llamada
barge_in_ratefloatFraccion de llamadas con barge-in
avg_turnsfloatTurnos de conversacion promedio
error_countintegerNumero de llamadas con errores

Eventos STT​

GET /analytics/stt-events

Eventos del ciclo de vida de conexion STT por llamada. Registra cuando las conexiones STT se abren, cierran, rechazan o expiran.

Parametros de Consulta​

ParametroTipoDescripcion
call_sidstringFiltrar por Twilio Call SID
event_typestringFiltrar por tipo de evento (ver abajo)
start_datedatetimeFiltrar eventos desde esta marca de tiempo
end_datedatetimeFiltrar eventos hasta esta marca de tiempo
limitintegerResultados maximos (por defecto 100, maximo 500)

Tipos de Evento​

TipoDescripcion
connection_openedConexion WebSocket STT establecida
connection_closedConexion STT cerrada normalmente
connection_rejectedConexion STT rechazada por el proveedor
timeoutTimeout de conexion STT
errorError de conexion STT
utterance_end_fallbackRecurrio a la deteccion de fin de enunciado

Respuesta​

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

Resumen de Eventos STT​

GET /analytics/stt-events/summary

Estadisticas agregadas de eventos STT en un rango de tiempo. Util para monitorear la salud de las conexiones STT.

Parametros de Consulta​

ParametroTipoDescripcion
start_datedatetimeFiltrar eventos desde esta marca de tiempo
end_datedatetimeFiltrar eventos hasta esta marca de tiempo

Respuesta​

{
  "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
}
CampoTipoDescripcion
total_eventsintegerTotal de eventos STT registrados
connections_openedintegerAperturas de conexion exitosas
connections_closedintegerCierres de conexion normales
connections_rejectedintegerConexiones rechazadas por el proveedor
timeoutsintegerTimeouts de conexion
errorsintegerErrores de conexion
utterance_end_fallbacksintegerRecurso a deteccion de fin de enunciado
avg_connection_duration_sfloat | nullDuracion promedio de conexion (segundos)
rejection_ratefloatRechazadas / (abiertas + rechazadas)
timeout_ratefloatTimeouts / abiertas