Analítica y resultados¶

Endpoints para consultar estadísticas agregadas, listar llamadas con paginación por cursor y obtener el detalle de una llamada (con transcripción y análisis).

La misma referencia, en otras dos formas

· Probar los endpoints — esta misma información, desplegable y con botón para ejecutar las consultas de lectura contra tu organización. · Ciclo de vida de una campaña — si buscabas el recorrido completo en orden en vez del contrato suelto.

Base URL: https://api.neuronstudio.ai

Autenticación: API Key (X-API-Key) o JWT (Authorization: Bearer). Todos son de lectura (GET) — una key con scope read o full puede usarlos.

Para sincronizar resultados de forma continua, sigue el patrón de polling en results-polling.md.

Índice¶

Método	Path	Rate limit
`GET`	`/api/analytics/stats`	30 / min
`GET`	`/api/analytics/calls`	—
`GET`	`/api/analytics/call/{call_id}`	—
`GET`	`/api/analytics/export`	60 / hora por org

`GET /api/analytics/stats`¶

Estadísticas agregadas de las campañas de tu organización.

Atributo	Valor
URL completa	`https://api.neuronstudio.ai/api/analytics/stats`
Autenticación	API Key / JWT
Scope	lectura
Rate limit	30 solicitudes / min

Parámetros de query¶

Parámetro	Tipo	Requerido	Descripción
`campaign_ids`	string	No	IDs separados por coma (ej. `123,124`).
`campaign_type`	string	No	`collections`, `sdr`, `cx` o `interviewer`.
`from_date`	string	No	Fecha desde, ISO 8601 (ej. `2026-02-01T00:00:00Z`).
`to_date`	string	No	Fecha hasta, ISO 8601.

Ejemplo de request¶

API_BASE_URL="https://api.neuronstudio.ai"

curl -s "$API_BASE_URL/api/analytics/stats?campaign_ids=123&from_date=2026-02-01T00:00:00Z" \
  -H "X-API-Key: nrn_live_0123456789abcdef0123456789abcdef"

Ejemplo de response (200)¶

{
  "success": true,
  "stats": {
    "total_calls": 1250,
    "completed_calls": 980,
    "payment_commitments": 387,
    "total_committed_amount": 1245750.50,
    "contact_rate": 0.784,
    "resolution_rate": 0.310,
    "sentiment_breakdown": {
      "positive": 524,
      "neutral": 328,
      "negative": 128
    },
    "outcome_breakdown": {
      "promised_payment": 387,
      "no_commitment": 412,
      "refused_payment": 95,
      "voicemail": 86
    }
  }
}

Campo	Significado
`total_calls`	Total de llamadas.
`completed_calls`	Llamadas completadas (contestadas).
`payment_commitments`	Cantidad de promesas de pago.
`total_committed_amount`	Monto total prometido.
`contact_rate`	Tasa de contacto (0.0–1.0).
`resolution_rate`	Tasa de resolución (0.0–1.0).
`sentiment_breakdown`	Conteo por sentimiento.
`outcome_breakdown`	Conteo por resultado de llamada.

Códigos de error¶

Código	Cuándo ocurre
`401`	No autenticado.
`429`	Más de 30 solicitudes en un minuto. Incluye `Retry-After`.

`GET /api/analytics/calls`¶

Lista las llamadas paginadas por cursor. Es el endpoint principal para sincronizar resultados.

Atributo	Valor
URL completa	`https://api.neuronstudio.ai/api/analytics/calls`
Autenticación	API Key / JWT
Scope	lectura
Rate limit	—

Parámetros de query¶

Parámetro	Tipo	Requerido	Descripción
`limit`	integer	No	Cantidad por página. Default `100`, máximo `100`.
`cursor`	string	No	Cursor de la página siguiente (valor `pagination.next_cursor` de la respuesta anterior).
`campaign_ids`	string	No	IDs separados por coma (ej. `123,124`).
`call_outcome`	string	No	Filtra por resultado (ej. `promised_payment`).
`sentiment`	string	No	`positive`, `neutral` o `negative`.
`payment_filter`	string	No	`committed` (prometió pagar) o `none`.
`campaign_type`	string	No	`collections`, `sdr`, `cx` o `interviewer`.
`from_date`	string	No	Fecha desde, ISO 8601.
`to_date`	string	No	Fecha hasta, ISO 8601.

Ejemplo de request¶

API_BASE_URL="https://api.neuronstudio.ai"

curl -s "$API_BASE_URL/api/analytics/calls?limit=100&campaign_ids=123&sentiment=positive" \
  -H "X-API-Key: nrn_live_0123456789abcdef0123456789abcdef"

Ejemplo de response (200)¶

{
  "success": true,
  "calls": [
    {
      "call_id": "call_abc",
      "campaign_id": 1,
      "client_name": "Juan",
      "lead_id": "L001",
      "to_number": "+525512345678",
      "call_duration": 42,
      "call_status": "completed",
      "call_outcome": "promised_payment",
      "sentiment": "positive",
      "payment_promised": true,
      "payment_amount": "5000.00",
      "payment_date": "2026-02-20",
      "summary": "Cliente reconoce la deuda y promete pagar el monto completo.",
      "start_timestamp": "2026-02-10T10:15:00Z"
    }
  ],
  "pagination": {
    "limit": 100,
    "count": 100,
    "has_more": true,
    "next_cursor": "eyJ0..."
  }
}

Cómo paginar¶

Haz la primera solicitud (con o sin cursor).
Procesa calls.
Si pagination.has_more es true, repite la solicitud agregando cursor=<pagination.next_cursor>.
Cuando has_more sea false, terminaste.

Ejemplo en Python:

import requests

API_BASE_URL = "https://api.neuronstudio.ai"
headers = {"X-API-Key": "nrn_live_0123456789abcdef0123456789abcdef"}

cursor = None
while True:
    params = {"limit": 100, "campaign_ids": "123"}
    if cursor:
        params["cursor"] = cursor
    resp = requests.get(f"{API_BASE_URL}/api/analytics/calls",
                        headers=headers, params=params).json()
    for call in resp["calls"]:
        print(call["call_id"], call["call_outcome"])
    if not resp["pagination"]["has_more"]:
        break
    cursor = resp["pagination"]["next_cursor"]

Campo de `pagination`	Significado
`limit`	Tamaño de página solicitado.
`count`	Cantidad de llamadas devueltas en esta página.
`has_more`	`true` si hay más páginas.
`next_cursor`	Cursor para la página siguiente.

Códigos de error¶

Código	Cuándo ocurre
`401`	No autenticado.
`400`	`cursor` inválido o `limit` fuera de rango.

`GET /api/analytics/call/{call_id}`¶

Detalle completo de una llamada: datos de la llamada, análisis con AI, transcripción y URL de grabación.

Atributo	Valor
URL completa	`https://api.neuronstudio.ai/api/analytics/call/{call_id}`
Autenticación	API Key / JWT
Scope	lectura
Rate limit	—

Parámetros de path¶

Parámetro	Tipo	Requerido	Descripción
`call_id`	string	Sí	ID de la llamada (ej. `call_abc`).

Ejemplo de request¶

API_BASE_URL="https://api.neuronstudio.ai"

curl -s "$API_BASE_URL/api/analytics/call/call_abc" \
  -H "X-API-Key: nrn_live_0123456789abcdef0123456789abcdef"

Ejemplo de response (200)¶

{
  "success": true,
  "call": {
    "call_id": "call_abc",
    "campaign_id": 1,
    "client_name": "Juan",
    "lead_id": "L001",
    "to_number": "+525512345678",
    "call_duration": 210,
    "call_status": "completed",
    "start_timestamp": "2026-02-10T10:15:00Z",
    "transcript": "Agente: Buenos días, ¿hablo con Juan?\nJuan: Sí, soy yo.\n...",
    "recording_url": "https://api.neuronstudio.ai/recordings/call_abc.mp3"
  },
  "analysis": {
    "call_outcome": "promised_payment",
    "sentiment": "positive",
    "payment_promised": true,
    "payment_amount": "5000.00",
    "payment_date": "2026-02-20",
    "summary": "Cliente reconoce la deuda y promete pagar el monto completo.",
    "customer_objections": [],
    "follow_up_needed": true,
    "analyzed_at": "2026-02-10T10:19:00Z"
  }
}

Campo de `analysis`	Significado
`call_outcome`	Resultado de la llamada (ej. `promised_payment`).
`sentiment`	`positive`, `neutral` o `negative`.
`payment_promised`	`true` / `false` — ¿prometió pagar?
`payment_amount`	Monto prometido (string decimal).
`payment_date`	Fecha prometida (`YYYY-MM-DD`).
`summary`	Resumen de la conversación.
`customer_objections`	Lista de objeciones detectadas.
`follow_up_needed`	`true` si requiere seguimiento.
`analyzed_at`	Timestamp del análisis (ISO 8601).

El análisis (sentimiento, resultado, resumen, objeciones) lo produce el motor de análisis con AI a partir de la transcripción de la llamada.

Códigos de error¶

Código	Cuándo ocurre
`401`	No autenticado.
`404`	No existe una llamada con ese `call_id` en tu organización.

`GET /api/analytics/export`¶

Devuelve un archivo Excel (.xlsx) con el detalle de llamadas de tu organización. Es el mismo archivo que genera el botón de exportar del panel.

A diferencia del resto de los endpoints de esta sección, la respuesta no es JSON: es el archivo binario, con el nombre sugerido en el header Content-Disposition.

Parámetros de query¶

Todos opcionales y combinables entre sí. Sin filtros, exporta todas las llamadas de tu organización.

Parámetro	Tipo	Valores	Descripción
`campaign_ids`	string	`"1,2,3"`	IDs de campaña separados por coma.
`campaign_type`	string	`collections`, `sdr`, `cx`, `interviewer`	Filtra por tipo de campaña.
`call_outcome`	string	ej. `promised_payment`	Filtra por resultado de la llamada.
`sentiment`	string	ej. `positive`	Filtra por sentimiento detectado.
`payment_filter`	string	`committed` \| `none`	Solo con compromiso de pago, o solo sin él.
`from_date`	string	`YYYY-MM-DD`	Desde esta fecha, inclusive.
`to_date`	string	`YYYY-MM-DD`	Hasta esta fecha, inclusive.
`exclude_inbound`	boolean	`true` \| `false` (default `false`)	Excluye las llamadas entrantes del archivo.

exclude_inbound viene apagado a propósito. Las llamadas entrantes no pertenecen a ninguna campaña saliente, así que sus columnas de campaña van vacías. Si tu operación es principalmente de cobranza, prenderlo limpia el archivo. Si tu organización trabaja solo llamadas entrantes, prenderlo te devuelve un archivo vacío.

Ejemplo de request¶

curl "https://api.neuronstudio.ai/api/analytics/export?campaign_ids=123&payment_filter=committed" \
  -H "X-API-Key: nrn_live_abcdef1234567890abcdef1234567890" \
  -o resultados.xlsx

Respuesta (200)¶

El cuerpo es el archivo .xlsx. Headers relevantes:

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename=analytics_miorg_20260817_143022.xlsx

El libro trae dos hojas cuando corresponde:

Hoja	Contenido
Detalle de llamadas	Una fila por llamada, con las columnas propias de tu CSV preservadas.
Promesas de Pago	Solo las filas donde hubo compromiso de pago. Se omite si no hubo ninguna.

Límites¶

60 exportaciones por hora, por organización.
250.000 filas por archivo. Si tu selección supera ese tope, el archivo se corta ahí; para volúmenes mayores, exporta por rango de fechas o por campaña.
Armar un libro grande puede tomar decenas de segundos. Configura un timeout generoso en tu cliente HTTP.

Códigos de error¶

Código	Cuándo ocurre
`400`	`campaign_ids` contiene un valor que no es numérico. Cuerpo: `{"error": "Invalid campaign_ids format"}`.
`401`	No autenticado.
`404`	Los filtros no dejaron ninguna fila. Cuerpo: `{"error": "No data to export"}`.
`429`	Superaste las 60 exportaciones por hora.

Cuerpo del 429:

{
  "error": "Too many exports. Please wait before exporting again.",
  "error_code": "RATE_LIMITED",
  "retry_after_seconds": 3600
}

Analítica y resultados¶

Índice¶

GET /api/analytics/stats¶

Parámetros de query¶

Ejemplo de request¶

Ejemplo de response (200)¶

Códigos de error¶

GET /api/analytics/calls¶

Parámetros de query¶

Ejemplo de request¶

Ejemplo de response (200)¶

Cómo paginar¶

Códigos de error¶

GET /api/analytics/call/{call_id}¶

Parámetros de path¶

Ejemplo de request¶

Ejemplo de response (200)¶

Códigos de error¶

GET /api/analytics/export¶

Parámetros de query¶

Ejemplo de request¶

Respuesta (200)¶

Límites¶

Códigos de error¶

`GET /api/analytics/stats`¶

`GET /api/analytics/calls`¶

`GET /api/analytics/call/{call_id}`¶

`GET /api/analytics/export`¶