# Listar llamadas

**POST** `/v3/list-calls`

Devuelve una lista paginada de llamadas con soporte para filtros avanzados. Los filtros pueden combinarse para consultas muy específicas: por agente, estado, número, dirección, fechas, duración, sentimiento del usuario y más.

> **Nota:** Este endpoint usa `POST` (no `GET`) para permitir filtros complejos en el cuerpo de la solicitud.

---

## Parámetros del cuerpo (todos opcionales)

| Campo | Tipo | Predeterminado | Máximo | Descripción |
|-------|------|----------------|--------|-------------|
| `filter_criteria` | object | — | — | Criterios de filtrado (se aplican con lógica AND). |
| `sort_order` | string | `descending` | — | Ordena por `start_timestamp`. Valores: `ascending` \| `descending` |
| `limit` | integer | 50 | 1000 | Cantidad máxima de registros a retornar. |
| `skip` | integer | 0 | — | Registros a omitir. No se puede usar junto con `pagination_key`. |
| `pagination_key` | string | — | — | Cursor opaco obtenido de una respuesta anterior. No se puede usar junto con `skip`. |

---

## Filtros disponibles (`filter_criteria`)

Todos los filtros son opcionales y se combinan con lógica AND.

### Filtro por agente

```json
"agent": [
  { "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD" },
  { "agent_id": "otro_agent_id", "version": [1, 2] }
]
```

Múltiples agentes se combinan con lógica OR.

### Filtros de texto (`StringFilter`)

Aplican a: `call_id`, `batch_call_id`, `from_number`, `to_number`

| Operador | Descripción |
|----------|-------------|
| `eq` | Igual a |
| `ne` | Distinto de |
| `sw` | Comienza con |
| `ew` | Termina con |
| `co` | Contiene |

Ejemplo:
```json
"from_number": { "operator": "eq", "value": "+14157774444" }
```

### Filtros de enumeración (`EnumFilter`)

Aplican a: `call_status`, `call_type`, `direction`, `user_sentiment`, `disconnection_reason`, `data_storage_setting`

```json
"direction": { "operator": "eq", "value": "outbound" }
```

```json
"call_status": { "operator": "eq", "value": "ended" }
```

Valores disponibles por campo:

| Campo | Valores |
|-------|---------|
| `call_status` | `not_connected` \| `ongoing` \| `ended` \| `error` |
| `call_type` | `phone_call` \| `web_call` |
| `direction` | `inbound` \| `outbound` |
| `user_sentiment` | `Positive` \| `Neutral` \| `Negative` \| `Unknown` |

### Filtros numéricos y de rango (`NumberFilter` / `RangeFilter`)

Aplican a: `start_timestamp`, `end_timestamp`, `duration_ms`, `combined_cost`, `e2e_latency_p50`

| Operador | Descripción |
|----------|-------------|
| `eq` | Igual a |
| `ne` | Distinto de |
| `gt` | Mayor que |
| `ge` | Mayor o igual que |
| `lt` | Menor que |
| `le` | Menor o igual que |
| `bt` | Entre dos valores (rango) |

Ejemplo — llamadas iniciadas después del 1 de mayo de 2025:
```json
"start_timestamp": { "operator": "ge", "value": 1746057600000 }
```

Ejemplo — llamadas de entre 60 y 300 segundos:
```json
"duration_ms": { "operator": "bt", "low_threshold": 60000, "high_threshold": 300000 }
```

### Filtro booleano (`BooleanFilter`)

Aplican a: `in_voicemail`, `call_successful`

```json
"in_voicemail": { "operator": "eq", "value": false }
```

### Filtros de variables dinámicas

```json
"dynamic_variables": [
  { "key": "campaña", "operator": "eq", "value": "reactivacion-mayo" }
]
```

---

## Respuesta — 200 OK

```json
{
  "pagination_key": "cursor_opaco_para_siguiente_pagina",
  "has_more": true,
  "items": [ /* array de objetos de llamada */ ]
}
```

| Campo | Descripción |
|-------|-------------|
| `pagination_key` | Cursor para obtener la siguiente página. `null` si no hay más resultados. |
| `has_more` | `true` si hay más registros disponibles. |
| `items` | Array de objetos de llamada. Contiene todos los campos de la llamada **excepto** la transcripción (para optimizar rendimiento). |

> Para obtener la transcripción de una llamada específica, usa [Obtener llamada](obtener-llamada.md).

---

## Ejemplos de solicitud

### Listar las últimas 20 llamadas

```bash
curl --request POST \
     --url https://calls.anunzi.net/v3/list-calls \
     --header 'Authorization: Bearer TU_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
  "limit": 20,
  "sort_order": "descending"
}'
```

### Listar llamadas salientes de un agente específico

```bash
curl --request POST \
     --url https://calls.anunzi.net/v3/list-calls \
     --header 'Authorization: Bearer TU_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
  "filter_criteria": {
    "agent": [{ "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD" }],
    "direction": { "operator": "eq", "value": "outbound" },
    "call_status": { "operator": "eq", "value": "ended" }
  },
  "limit": 100
}'
```

### Paginación — segunda página

```bash
curl --request POST \
     --url https://calls.anunzi.net/v3/list-calls \
     --header 'Authorization: Bearer TU_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
  "limit": 50,
  "pagination_key": "cursor_opaco_de_respuesta_anterior"
}'
```

---

## Códigos de estado

| Código | Descripción |
|--------|-------------|
| `200` | Listado devuelto correctamente. |
| `400` | Formato de solicitud inválido. |
| `401` | API Key ausente o inválida. |
| `429` | Límite de solicitudes alcanzado. |
| `500` | Error interno del servidor. |