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

# Call List

> List calls with optional filtering and pagination

Retrieve a list of calls with optional filtering by status, agent, direction, and time range.

<Note>
  This endpoint uses POST to support complex filter criteria in the request body.
</Note>

## Request Body

<ParamField body="filter_criteria" type="object">
  Optional filters to apply.

  <Expandable title="Filter options">
    <ParamField body="agent_id" type="array">
      Filter by agent IDs (array of UUIDs).
    </ParamField>

    <ParamField body="call_status" type="array">
      Filter by status. See [Call](/api-reference/models/call) for all status values.
    </ParamField>

    <ParamField body="direction" type="array">
      Filter by direction: `incoming`, `outgoing`.
    </ParamField>

    <ParamField body="start_timestamp" type="object">
      Filter by time range (Unix milliseconds).

      ```json theme={null}
      {
        "lower_threshold": 1704067200000,
        "upper_threshold": 1704153600000
      }
      ```
    </ParamField>

    <ParamField body="include_test_calls" type="boolean" default="false">
      Include test calls in results. Test calls are excluded by default.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="sort_order" type="string" default="descending">
  Sort order: `ascending` or `descending` (by start time).
</ParamField>

<ParamField body="limit" type="integer" default="50">
  Maximum number of results (1-1000).
</ParamField>

<ParamField body="pagination_key" type="string">
  Cursor for pagination. Use the last `call_id` from the previous page.
</ParamField>

## Response

Returns an object with `calls` (array of lightweight call objects) and `total_count`. These include core metadata (status, agent, timing) but **omit** `transcript`, `summary`, `recording_url`, `detected_gender`, `vars_provided`, `vars_extracted`, and `vars_collected` for performance. Use [Get Call](/api-reference/call-get) to retrieve the full call object.

<ResponseField name="calls" type="array">
  Array of call objects with the following fields:

  <Expandable title="Call object properties">
    <ResponseField name="call_id" type="string">Unique call identifier (UUID)</ResponseField>
    <ResponseField name="call_type" type="string">`phone_call` or `web_call`</ResponseField>
    <ResponseField name="call_status" type="string">Current call status (see [Call](/api-reference/models/call) for values)</ResponseField>

    <ResponseField name="agent" type="object">
      Agent that handled the call.

      <Expandable title="Agent properties">
        <ResponseField name="name" type="string">Agent name</ResponseField>
        <ResponseField name="version" type="integer">Agent version used for this call</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="from_number" type="string">Caller's phone number</ResponseField>
    <ResponseField name="to_number" type="string">Called phone number</ResponseField>
    <ResponseField name="direction" type="string">`incoming` or `outgoing`</ResponseField>
    <ResponseField name="start_timestamp" type="integer">Unix timestamp (ms) when the call started</ResponseField>
    <ResponseField name="duration_ms" type="integer">Call duration in milliseconds</ResponseField>
    <ResponseField name="is_test_call" type="boolean">Whether this call was made by a test user contact</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total number of calls matching the filter criteria (for pagination).
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.voicy.co/functions/v1/call-list \
    -H "Authorization: Bearer voicy_sk_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "filter_criteria": {
        "call_status": ["user_hangup", "agent_hangup"]
      },
      "sort_order": "descending",
      "limit": 10
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.voicy.co/functions/v1/call-list', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer voicy_sk_live_xxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      filter_criteria: {
        call_status: ['user_hangup', 'agent_hangup'],
      },
      sort_order: 'descending',
      limit: 10,
    }),
  });

  const calls = await response.json();
  ```

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

  response = requests.post(
      'https://api.voicy.co/functions/v1/call-list',
      headers={
          'Authorization': 'Bearer voicy_sk_live_xxx',
          'Content-Type': 'application/json',
      },
      json={
          'filter_criteria': {
              'call_status': ['user_hangup', 'agent_hangup'],
          },
          'sort_order': 'descending',
          'limit': 10,
      },
  )

  calls = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "calls": [
      {
        "call_id": "550e8400-e29b-41d4-a716-446655440000",
        "call_type": "phone_call",
        "call_status": "user_hangup",
        "agent": {
          "name": "Customer Support Agent",
          "version": 2
        },
        "from_number": "+15551234567",
        "to_number": "+15559876543",
        "direction": "outgoing",
        "start_timestamp": 1704067200000,
        "duration_ms": 120000
      },
      {
        "call_id": "550e8400-e29b-41d4-a716-446655440002",
        "call_type": "phone_call",
        "call_status": "agent_hangup",
        "agent": {
          "name": "Customer Support Agent",
          "version": 1
        },
        "from_number": "+15559876543",
        "to_number": "+15551234567",
        "direction": "incoming",
        "start_timestamp": 1704063600000,
        "duration_ms": 180000
      }
    ],
    "total_count": 42
  }
  ```
</ResponseExample>