Listar Análisis

Obtiene una lista de todos los análisis de tu cuenta. Soporta filtrado, búsqueda y paginación.

Endpoint

GET /api/v1/analysis/

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

Listar análisis es gratuito - no cuenta contra tus límites de uso.

Parámetros de Query

Parámetro	Tipo	Requerido	Default	Descripción
status_filter	string	No	-	Filtrar por estado: processing, completed, o failed
agent_id	string	No	-	Filtrar por ID de agente específico
contact_id	string	No	-	Filtrar por ID de contacto específico
search	string	No	-	Buscar en agent_id y contact_id (sin distinción de mayúsculas)
limit	integer	No	100	Número máximo de resultados a devolver (1-1000)
offset	integer	No	0	Número de resultados a omitir (para paginación)

Ejemplos de Filtros

# Obtener solo análisis completados
?status_filter=completed

# Obtener todos los análisis de un agente específico
?agent_id=agent_001

# Obtener todos los análisis de un contacto específico
?contact_id=customer_12345

# Buscar análisis que contengan "agent_001"
?search=agent_001

# Combinar filtros
?status_filter=completed&agent_id=agent_001&limit=50

Response

Devuelve un objeto AnalysisList conteniendo un array de análisis y metadata de paginación.

Response Exitoso (200 OK)

{
  "object": "list",
  "data": [
    {
      "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...",
        "segments": [...],
        "language": "en"
      },
      "results": {
        "compliance": {...},
        "quality": {...},
        "summary": "..."
      },
      "metadata": {
        "webhook_url": "https://your-app.com/webhooks/analysis",
        "completed_at": "2024-01-15T14:32:15.123Z",
        "processing_time_ms": 45230,
        "error_message": null
      }
    },
    {
      "id": "660f9511-f3ac-52e5-b827-557766551111",
      "object": "analysis",
      "created": 1705330800,
      "status": "processing",
      "livemode": false,
      "call": {
        "agent_id": "agent_002",
        "contact_id": "customer_67890",
        "duration_ms": 98200,
        "duration_seconds": 98.2
      },
      "audio": {
        "url": "https://s3.amazonaws.com/callcov-audio/...",
        "size_bytes": 823456,
        "format": "mp3",
        "duration_seconds": 98.2
      },
      "transcript": null,
      "results": null,
      "metadata": {
        "webhook_url": null,
        "completed_at": null,
        "processing_time_ms": null,
        "error_message": null
      }
    }
  ],
  "has_more": true,
  "total": 247
}

Campos del Response

Campo	Tipo	Descripción
object	string	Siempre "list"
data	array	Array de objetos AnalysisResponse
has_more	boolean	Si hay más resultados disponibles
total	integer	Número total de análisis que coinciden con los filtros

Paginación

Los resultados se devuelven en orden cronológico inverso (más nuevos primero) por fecha de creación.

Paginación Básica

import requests

url = "https://api.callcov.com/api/v1/analysis/"
headers = {"X-API-Key": "sk_live_abc123..."}

# Obtener primera página (análisis 0-99)
response = requests.get(url, headers=headers, params={
    "limit": 100,
    "offset": 0
})

# Obtener segunda página (análisis 100-199)
response = requests.get(url, headers=headers, params={
    "limit": 100,
    "offset": 100
})

Iterar por Todas las Páginas

import requests

def get_all_analyses(api_key, status_filter=None):
    """
    Obtener todos los análisis en todas las páginas.

    Args:
        api_key: Tu clave de API
        status_filter: Filtro de estado opcional

    Returns:
        Lista de todos los análisis
    """
    url = "https://api.callcov.com/api/v1/analysis/"
    headers = {"X-API-Key": api_key}

    all_analyses = []
    offset = 0
    limit = 100

    while True:
        params = {"limit": limit, "offset": offset}
        if status_filter:
            params["status_filter"] = status_filter

        response = requests.get(url, headers=headers, params=params)
        data = response.json()

        all_analyses.extend(data['data'])

        if not data['has_more']:
            break

        offset += limit

    return all_analyses

# Uso
completed_analyses = get_all_analyses(
    api_key="sk_live_abc123...",
    status_filter="completed"
)
print(f"Total de análisis completados: {len(completed_analyses)}")

Ejemplos

# Obtener todos los análisis
curl "https://api.callcov.com/api/v1/analysis/" \
-H "X-API-Key: sk_live_abc123..."

# Obtener solo análisis completados
curl "https://api.callcov.com/api/v1/analysis/?status_filter=completed" \
-H "X-API-Key: sk_live_abc123..."

# Filtrar por agente
curl "https://api.callcov.com/api/v1/analysis/?agent_id=agent_001" \
-H "X-API-Key: sk_live_abc123..."

# Búsqueda con paginación
curl "https://api.callcov.com/api/v1/analysis/?search=customer&limit=50&offset=0" \
-H "X-API-Key: sk_live_abc123..."

Ejemplos de Filtrado

Obtener Análisis Completados Recientes

import requests

url = "https://api.callcov.com/api/v1/analysis/"
headers = {"X-API-Key": "sk_live_abc123..."}

response = requests.get(url, headers=headers, params={
    "status_filter": "completed",
    "limit": 10  # Últimos 10 completados
})

analyses = response.json()['data']
for analysis in analyses:
    quality_score = analysis['results']['quality']['overall_score']
    print(f"{analysis['call']['contact_id']}: {quality_score}")

Obtener Todos los Análisis de un Agente

def get_agent_analyses(api_key, agent_id):
    """Obtener todos los análisis de un agente específico"""
    url = "https://api.callcov.com/api/v1/analysis/"
    headers = {"X-API-Key": api_key}

    response = requests.get(url, headers=headers, params={
        "agent_id": agent_id,
        "limit": 1000  # Ajustar según sea necesario
    })

    data = response.json()
    return data['data'], data['total']

analyses, total = get_agent_analyses("sk_live_abc123...", "agent_001")
print(f"El agente agent_001 tiene {total} análisis en total")

Buscar en Análisis

# Buscar análisis que contengan "customer_123"
response = requests.get(url, headers=headers, params={
    "search": "customer_123"
})

# Esto busca tanto en agent_id COMO en contact_id

Obtener Análisis Fallidos para Debugging

response = requests.get(url, headers=headers, params={
    "status_filter": "failed",
    "limit": 50
})

failed_analyses = response.json()['data']
for analysis in failed_analyses:
    error = analysis['metadata']['error_message']
    print(f"Análisis {analysis['id']} falló: {error}")

Consejos de Rendimiento

1. Usar Filtros: Filtrar por estado o agent_id para reducir el tamaño del conjunto de resultados
2. Limitar Resultados: Solicitar solo el número de resultados que necesitas
3. Cachear Resultados: Cachear los resultados de lista para evitar llamadas de API repetidas
4. Usar Webhooks: En lugar de hacer polling al endpoint de lista para nuevas completaciones, usar webhooks

Errores

401 Unauthorized

Autenticación inválida o faltante:

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

422 Validation Error

Valores de parámetros inválidos:

{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "asegurar que este valor sea menor o igual a 1000",
      "type": "value_error.number.not_le"
    }
  ]
}

Casos de Uso Comunes

Dashboard: Mostrar Actividad Reciente

# Obtener los últimos 20 análisis para el dashboard
response = requests.get(url, headers=headers, params={"limit": 20})
recent = response.json()['data']

Analítica: Calcular Puntaje de Calidad Promedio

# Obtener todos los análisis completados
all_analyses = get_all_analyses(
    api_key="sk_live_abc123...",
    status_filter="completed"
)

# Calcular puntaje de calidad promedio
total_score = sum(
    a['results']['quality']['overall_score']
    for a in all_analyses
    if a['results']
)
avg_score = total_score / len(all_analyses)
print(f"Puntaje de calidad promedio: {avg_score:.2f}")

Reporte de Rendimiento de Agente

# Obtener todos los análisis completados de un agente específico
response = requests.get(url, headers=headers, params={
    "agent_id": "agent_001",
    "status_filter": "completed"
})

agent_analyses = response.json()['data']

# Calcular métricas
total_calls = len(agent_analyses)
avg_quality = sum(a['results']['quality']['overall_score'] for a in agent_analyses) / total_calls
avg_compliance = sum(a['results']['compliance']['score'] for a in agent_analyses) / total_calls

print(f"Reporte del Agente agent_001:")
print(f"  Total de llamadas: {total_calls}")
print(f"  Calidad promedio: {avg_quality:.2f}")
print(f"  Cumplimiento promedio: {avg_compliance:.2f}")

Seguridad

• Aislamiento de Usuarios: Solo puedes listar análisis que pertenecen a tu cuenta
• Alcance de Clave de API: Las claves de API tienen alcance a tu cuenta de usuario
• Sin Acceso entre Cuentas: No se pueden ver análisis de otros usuarios

Relacionado

• Crear Análisis - Enviar audio para análisis
• Obtener Análisis - Obtener análisis específico por ID
• Resumen de API - Información general de paginación