> For the complete documentation index, see [llms.txt](https://anunzi-ai.gitbook.io/anunzi-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://anunzi-ai.gitbook.io/anunzi-docs/api-calls/listar-llamadas.md).

# 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](/anunzi-docs/api-calls/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.      |