> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verbeo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List calls

> Page through your workspace's call history, newest first, filtered by type, assistant, campaign, number, date, duration, cost or how the call ended.

Returns the calls of the workspace your API key belongs to, newest first. Each item carries the call's light fields; read one call with [Get call](/api-reference/calls/get-v2) for its transcript, recording, summary and analysis.

<Note>
  This read is a `POST` because a list query is a document: arrays and numbers arrive typed as themselves. It changes nothing.
</Note>

## Body

Every filter is optional, and together they all apply. An empty array is the same as leaving the filter out.

<ParamField body="page" type="number" default="1">
  1-based page number. Pass back `pagination.next_cursor` from the previous response.
</ParamField>

<ParamField body="size" type="number" default="50">
  Page size, between `1` and `1000`.
</ParamField>

<ParamField body="call_types" type="string[]">
  Any of `inbound`, `outbound`, `web`.
</ParamField>

<ParamField body="agent_ids" type="string[]">
  Assistant UUIDs.
</ParamField>

<ParamField body="campaign_ids" type="string[]">
  Campaign UUIDs: calls placed to those campaigns' contacts.
</ParamField>

<ParamField body="from_numbers" type="string[]">
  Numbers the calls came from, exactly as stored.
</ParamField>

<ParamField body="to_number" type="string">
  Part of the number called, e.g. `5550123`.
</ParamField>

<ParamField body="call_id" type="string">
  One call's UUID.
</ParamField>

<ParamField body="created_after" type="string">
  ISO 8601 date-time with an offset, e.g. `2026-10-01T00:00:00Z`. Inclusive.
</ParamField>

<ParamField body="created_before" type="string">
  ISO 8601 date-time with an offset. Inclusive.
</ParamField>

<ParamField body="duration_min" type="number">
  Seconds, inclusive. `duration_max` is the upper bound.
</ParamField>

<ParamField body="cost_min" type="number">
  Cents, inclusive. `cost_max` is the upper bound.
</ParamField>

<ParamField body="disconnection_reasons" type="string[]">
  How the calls ended, e.g. `user_hangup`, `agent_hangup`, `dial_no_answer`.
</ParamField>

Each array holds at most 100 values.

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.verbeo.ai/v2/call/list" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "size": 20, "call_types": ["outbound"], "created_after": "2026-10-01T00:00:00Z" }'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch("https://api.verbeo.ai/v2/call/list", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VERBEO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ size: 20, call_types: ["outbound"] }),
  });
  const { data, pagination } = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  res = requests.post(
      "https://api.verbeo.ai/v2/call/list",
      headers={"Authorization": f"Bearer {os.environ['VERBEO_API_KEY']}"},
      json={"size": 20, "call_types": ["outbound"]},
  )
  body = res.json()
  calls, pagination = body["data"], body["pagination"]
  ```
</CodeGroup>

## Response

`200 OK`. Standard envelope plus pagination — see [Responses](/api-reference/responses#list-responses-and-pagination). `next_cursor` is the next **page number**, or `null` on the last page. Stop there: a page past the last one answers `500 INTERNAL_ERROR`, and sending it again does not help.

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "b7a3c1e4-94f2-4c9d-a8e0-5d9f6c2a1b34",
      "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
      "agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "agent_name": "Customer Support",
      "call_type": "outbound",
      "from_number": "+14155550100",
      "to_number": "+14155550123",
      "status": "completed",
      "duration": 94,
      "cost": 21,
      "started_at": "2026-10-01T10:30:00.123+00:00",
      "answered_at": "2026-10-01T10:30:06.410+00:00",
      "ended_at": "2026-10-01T10:31:40.002+00:00",
      "disconnection_reason": "user_hangup",
      "created_at": "2026-10-01T10:30:00.101+00:00",
      "updated_at": "2026-10-01T10:31:41.500+00:00"
    }
  ],
  "pagination": { "total": 1, "count": 1, "next_cursor": null }
}
```

<ResponseField name="duration" type="number | null">Talk time in seconds.</ResponseField>
<ResponseField name="cost" type="number | null">What the call cost, in **cents**.</ResponseField>
<ResponseField name="agent_name" type="string | null">`null` when the assistant has since been deleted.</ResponseField>

## Errors

| Code | Status | When |
| - | - | - |
| `VALIDATION_FAILED` | 422 | A malformed filter — the message names it, e.g. `created_after: must be an ISO 8601 date-time`. |
| `UNAUTHORIZED` | 401 | Invalid, inactive or expired key. A request with no `Authorization: Bearer vbr_…` header is a `401` too, but [outside the envelope](/api-reference/errors). |
| `FORBIDDEN` | 403 | A public (`vbr_pub_…`) key. |
| `INTERNAL_ERROR` | 500 | A page past the last one (do not retry it), or an unexpected failure. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.