# 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](/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.      |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.anunzi.net/api-calls/listar-llamadas.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.