Obtener Análisis

Obtiene un análisis específico por su ID único. Usa este endpoint para verificar el estado y obtener resultados de un análisis.

Endpoint

GET /api/v1/analysis/{analysis_id}

Autenticación

Requiere clave de API o token JWT.

Método	Header	Ejemplo
Clave de API	`X-API-Key: {api_key}`	`X-API-Key: sk_live_abc123...`
Token JWT	`Authorization: Bearer {token}`	`Authorization: Bearer eyJhbGc...`

Endpoint Gratuito

Obtener análisis es gratuito - no cuenta contra tus límites de uso. Solo crear nuevos análisis consume minutos.

Parámetros de Path

Parámetro	Tipo	Requerido	Descripción
`analysis_id`	UUID	Sí	Identificador único del análisis devuelto cuando se creó el análisis

Response

Devuelve el objeto AnalysisResponse completo con el estado actual y resultados (si se completó).

Response Exitoso (200 OK)

Cuando el análisis aún está procesando:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "analysis",
  "created": 1705334400,
  "status": "processing",
  "livemode": false,
  "call": {
    "agent_id": "agent_001",
    "contact_id": "customer_12345",
    "duration_ms": 125500,
    "duration_seconds": 125.5
  },
  "audio": {
    "url": "https://s3.amazonaws.com/callcov-audio/...",
    "size_bytes": 1048576,
    "format": "wav",
    "duration_seconds": 125.5
  },
  "transcript": null,
  "results": null,
  "metadata": {
    "webhook_url": "https://your-app.com/webhooks/analysis",
    "completed_at": null,
    "processing_time_ms": null,
    "error_message": null
  }
}

Cuando el análisis está completado:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "analysis",
  "created": 1705334400,
  "status": "completed",
  "livemode": false,
  "call": {
    "agent_id": "agent_001",
    "contact_id": "customer_12345",
    "duration_ms": 125500,
    "duration_seconds": 125.5
  },
  "audio": {
    "url": "https://s3.amazonaws.com/callcov-audio/...",
    "size_bytes": 1048576,
    "format": "wav",
    "duration_seconds": 125.5
  },
  "transcript": {
    "text": "Transcripción completa de la llamada...",
    "segments": [
      {
        "speaker": "A",
        "text": "Hola, ¿en qué puedo ayudarte?",
        "start": 0.0,
        "end": 2.5
      },
      {
        "speaker": "B",
        "text": "Necesito ayuda con mi cuenta.",
        "start": 2.8,
        "end": 5.2
      }
    ],
    "language": "en"
  },
  "results": {
    "compliance": {
      "score": 0.92,
      "issues": [],
      "highlights": ["Saludo apropiado", "Comunicación clara"]
    },
    "quality": {
      "overall_score": 0.88,
      "communication_score": 0.90,
      "professionalism_score": 0.85
    },
    "summary": "El agente manejó la consulta del cliente profesionalmente...",
    "action_items": ["Dar seguimiento al problema de la cuenta"],
    "sentiment": {
      "agent": "positive",
      "customer": "neutral"
    }
  },
  "metadata": {
    "webhook_url": "https://your-app.com/webhooks/analysis",
    "completed_at": "2024-01-15T14:32:15.123Z",
    "processing_time_ms": 45230,
    "error_message": null
  }
}

Campos del Response

Campo	Tipo	Descripción
`id`	UUID	Identificador único del análisis
`object`	string	Siempre "analysis"
`created`	integer	Timestamp Unix de creación
`status`	string	Estado actual: "processing", "completed", o "failed"
`livemode`	boolean	Siempre false (modo test no implementado)
`call.agent_id`	string	Tu identificador del agente
`call.contact_id`	string	Tu identificador del contacto
`call.duration_ms`	integer	Duración del audio en milisegundos
`call.duration_seconds`	float	Duración del audio en segundos (calculado)
`audio.url`	string	URL S3 donde se almacena el audio
`audio.size_bytes`	integer	Tamaño del archivo en bytes
`audio.format`	string	Formato de audio (wav, mp3, etc.)
`audio.duration_seconds`	float	Duración del audio en segundos
`transcript`	object	Información de transcripción (null hasta completarse)
`transcript.text`	string	Texto completo de la transcripción
`transcript.segments`	array	Segmentos de transcripción con identificación de hablante
`transcript.language`	string	Código de idioma detectado
`results`	object	Resultados del análisis (null hasta completarse)
`results.compliance`	object	Análisis de cumplimiento con puntaje y problemas
`results.quality`	object	Puntajes de calidad
`results.summary`	string	Resumen de la llamada generado por IA
`results.action_items`	array	Items de acción identificados
`results.sentiment`	object	Análisis de sentimiento para agente y cliente
`metadata.webhook_url`	string	Tu URL de webhook (si se proporcionó)
`metadata.completed_at`	datetime	Timestamp de completación (null hasta completarse)
`metadata.processing_time_ms`	integer	Tiempo total de procesamiento en ms
`metadata.error_message`	string	Mensaje de error si el estado es "failed"

Valores de Estado

Estado	Descripción
`processing`	El análisis se está procesando actualmente
`completed`	Análisis completado exitosamente, resultados disponibles
`failed`	El análisis falló, verificar `error_message` para detalles

Ejemplos

# Usando Clave de API
curl https://api.callcov.com/api/v1/analysis/550e8400-e29b-41d4-a716-446655440000 \
-H "X-API-Key: sk_live_abc123..."

# Usando Token JWT
curl https://api.callcov.com/api/v1/analysis/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer eyJhbGc..."

Polling para Resultados

Si no proporcionaste una URL de webhook durante la creación, necesitarás hacer polling a este endpoint para verificar cuándo el análisis se complete.

Patrón de Polling

import requests
import time

def wait_for_analysis(analysis_id, api_key, timeout=300, interval=5):
    """
    Hacer polling para la completación del análisis.

    Args:
        analysis_id: UUID del análisis
        api_key: Tu clave de API
        timeout: Tiempo máximo a esperar (segundos)
        interval: Tiempo entre polls (segundos)

    Returns:
        Objeto de análisis completado o None si hay timeout
    """
    url = f"https://api.callcov.com/api/v1/analysis/{analysis_id}"
    headers = {"X-API-Key": api_key}

    elapsed = 0
    while elapsed < timeout:
        response = requests.get(url, headers=headers)

        if response.status_code == 200:
            analysis = response.json()

            if analysis['status'] == 'completed':
                return analysis
            elif analysis['status'] == 'failed':
                raise Exception(f"Análisis falló: {analysis['metadata']['error_message']}")

        time.sleep(interval)
        elapsed += interval

    return None  # Timeout

# Uso
analysis = wait_for_analysis(
    analysis_id="550e8400-e29b-41d4-a716-446655440000",
    api_key="sk_live_abc123...",
    timeout=300,
    interval=5
)

if analysis:
    print("¡Análisis completo!")
    print(analysis['results'])
else:
    print("Timeout esperando el análisis")

Usa Webhooks en su Lugar

El polling es ineficiente y puede alcanzar límites de tasa. Usa webhooks para aplicaciones de producción para recibir notificación inmediatamente cuando el análisis se complete.

Errores

401 Unauthorized

Autenticación inválida o faltante:

{
  "detail": "Credenciales de autenticación inválidas"
}

404 Not Found

El análisis no existe o no pertenece a tu cuenta:

{
  "detail": "Análisis no encontrado"
}

Seguridad

Aislamiento de Usuarios: Solo puedes obtener análisis que pertenecen a tu cuenta
Alcance de Clave de API: Las claves de API tienen alcance a tu cuenta de usuario
Validación de JWT: Los tokens JWT se validan por expiración y firma

Relacionado

Crear Análisis - Enviar audio para análisis
Listar Análisis - Listar todos tus análisis
Guía de Webhooks - Recibir notificación cuando se complete

Endpoint​

Autenticación​

Parámetros de Path​

Response​

Response Exitoso (200 OK)​

Campos del Response​

Valores de Estado​

Ejemplos​

Polling para Resultados​

Patrón de Polling​

Errores​

401 Unauthorized​

404 Not Found​

Seguridad​

Relacionado​