Obtener resultados (polling)¶

Esta página explica cómo obtener los resultados de tus campañas: transcripciones, sentimiento, promesas de pago y resúmenes de cada llamada.

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

Cómo se obtienen los resultados hoy¶

Los resultados se obtienen por polling (consulta periódica), combinando dos endpoints:

1. GET /api/analytics/calls — lista las llamadas paginadas por cursor (lo usas para barrer todas las llamadas nuevas).
2. GET /api/analytics/call/{call_id} — detalle completo de una llamada (transcripción completa + análisis).

La entrega por webhooks (push) está en desarrollo; hoy la sincronización es por consulta (polling). No existe forma de registrar una URL de webhook vía la API pública: el cliente consulta los resultados, no los recibe empujados.

Patrón de sincronización recomendado¶

La idea: cada N minutos, traer las llamadas nuevas filtrando por fecha (o por campaña), paginando con el cursor hasta agotar las páginas.

1. Define una ventana. Guarda la marca de tiempo de tu última sincronización y úsala como from_date en la próxima corrida.
2. Filtra por from_date (y opcionalmente campaign_ids o to_date).
3. Pagina con cursor hasta que pagination.has_more sea false.
4. Pide el detalle con GET /api/analytics/call/{call_id} solo para las llamadas que necesiten la transcripción completa.
5. Repite cada N minutos (por ejemplo, cada 5–10 minutos durante una campaña activa).

Filtros útiles en /api/analytics/calls¶

Ejemplo completo (Python)¶

Sincroniza todas las llamadas nuevas desde la última corrida, paginando por cursor:

import requests
from datetime import datetime, timezone

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

# Marca de la última sincronización (persístela entre corridas).
from_date = "2026-02-10T00:00:00Z"

def sync_calls(from_date, campaign_ids=None):
    cursor = None
    nuevas = []
    while True:
        params = {"limit": 100, "from_date": from_date}
        if campaign_ids:
            params["campaign_ids"] = campaign_ids
        if cursor:
            params["cursor"] = cursor

        resp = requests.get(
            f"{API_BASE_URL}/api/analytics/calls",
            headers=headers, params=params,
        ).json()

        nuevas.extend(resp["calls"])

        if not resp["pagination"]["has_more"]:
            break
        cursor = resp["pagination"]["next_cursor"]
    return nuevas

llamadas = sync_calls(from_date, campaign_ids="123")
for call in llamadas:
    if call.get("payment_promised"):
        print(f"{call['client_name']}: ${call['payment_amount']} "
              f"el {call['payment_date']}")

# Detalle (transcripción completa) de una llamada puntual:
detalle = requests.get(
    f"{API_BASE_URL}/api/analytics/call/{llamadas[0]['call_id']}",
    headers=headers,
).json()
print(detalle["call"]["transcript"])

# Actualiza tu marca para la próxima corrida:
nueva_marca = datetime.now(timezone.utc).isoformat()

Ejemplo de barrido por cursor (Bash)¶

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

cursor=""
while : ; do
  url="$API_BASE_URL/api/analytics/calls?limit=100&from_date=2026-02-10T00:00:00Z"
  [ -n "$cursor" ] && url="$url&cursor=$cursor"

  resp=$(curl -s "$url" -H "X-API-Key: $API_KEY")
  echo "$resp" | jq '.calls[] | {call_id, call_outcome, payment_promised}'

  has_more=$(echo "$resp" | jq -r '.pagination.has_more')
  [ "$has_more" = "true" ] || break
  cursor=$(echo "$resp" | jq -r '.pagination.next_cursor')
done

Buenas prácticas¶

• Persiste la marca de tiempo de la última sincronización y úsala como from_date. Así solo traes llamadas nuevas en cada corrida.
• Respeta el rate limit de GET /api/analytics/stats (30 / min). El listado de llamadas no tiene rate limit fijo, pero evita hacer polling más seguido de lo necesario (cada 5–10 minutos suele alcanzar).
• Reserva el detalle por llamada (/api/analytics/call/{id}) para cuando realmente necesites la transcripción completa: el listado ya trae un summary y los campos de análisis principales.
• El análisis tarda unos segundos después de que termina la llamada. Si una llamada aparece sin analysis, vuelve a consultarla en la siguiente corrida.