---
title: "List calls"
method: GET
path: "/calls"
tags: ["Calls"]
---

# List calls

`GET /calls`

## Request

- Base URL: `https://vocenya.com/api/public/v1`
- URL: `https://vocenya.com/api/public/v1/calls`
- Auth: HTTP bearer

Your calls, newest first.

## Query parameters

- `direction` 'inbound' | 'outbound'
- `status` 'ringing' | 'in_progress' | 'completed' | 'missed' | 'failed' | 'blocked': | | |---| | `ringing` <br/> | | `in_progress` <br/> | | `completed` <br/> | | `missed` <br/> | | `failed` <br/> | | `blocked` <br/> The caller's number is on the client's blocked callers list: turned away before anyone answered. |
- `since` string, date-time
- `until` string, date-time
- `spam` 'true' | 'false' | '1' | '0'
- `phone_number` string
- `per_page` integer
- `cursor` string, nullable

## Response `200`

Paginated set of `CallResource`

- object
  - `data` CallResource[], required
    - `id` integer, required
    - `livemode` boolean, required: `true` for live data, `false` for test data (created with a `vk_test_` key).
    - `direction` 'inbound' | 'outbound', required
    - `status` 'ringing' | 'in_progress' | 'completed' | 'missed' | 'failed' | 'blocked', required: | | |---| | `ringing` <br/> | | `in_progress` <br/> | | `completed` <br/> | | `missed` <br/> | | `failed` <br/> | | `blocked` <br/> The caller's number is on the client's blocked callers list: turned away before anyone answered. |
    - `from_number` string, required
    - `caller_name` string, nullable, required: The caller's name as the carrier reported it (CNAM), when known.
    - `to_number` string, required
    - `spam` boolean, required: Whether the call was judged spam: by the receptionist, or because the number is on your blocked callers list (`status` is then `blocked`).
    - `routed_to` 'ai_agent' | 'human_queue' | 'forward_number' | 'voicemail' | 'team' | 'extension', required: | | |---| | `ai_agent` <br/> | | `human_queue` <br/> | | `forward_number` <br/> | | `voicemail` <br/> | | `team` <br/> The team ring list, rung the way it is set to ring (everyone at once or one after another), before the next step. | | `extension` <br/> One extension of the phone system (target: its id): a person's phones, a group, a desk phone (phone_system flag). |
    - `started_at` string, required
    - `answered_at` string, nullable, required
    - `ended_at` string, nullable, required
    - `duration_seconds` integer, nullable, required
    - `disposition` string, nullable, required
    - `summary` string, nullable: The AI's summary of the call. Not included for HIPAA-mode accounts.
    - `handoff_summary` string, nullable: What the AI told the person it handed the call to. Not included for HIPAA-mode accounts.
    - `transcript` object[], nullable: The conversation, turn by turn. Only on `GET /calls/{id}`, and never for HIPAA-mode accounts.
      - `role` string, required
      - `text` string, required
    - `agent_notes` string, nullable: The message or notes a live agent took when they answered the call (see `disposition: message_taken`). Not included for HIPAA-mode accounts.
    - `lead_ids` unknown[]: Leads the AI captured on this call. Only on `GET /calls/{id}`.
      - unknown
    - `created_at` string, nullable, required
  - `links` object, required
    - `first` string, nullable, required
    - `last` string, nullable, required
    - `prev` string, nullable, required
    - `next` string, nullable, required
  - `meta` object, required
    - `path` string, nullable, required: Base path for paginator generated URLs.
    - `per_page` integer, required: Number of items shown per page.
    - `next_cursor` string, nullable, required: The "cursor" that points to the next set of items.
    - `prev_cursor` string, nullable, required: The "cursor" that points to the previous set of items.

## Other responses

- `401`: The API key is missing, invalid, expired or revoked.
- `403`: The key does not have the `calls:read` scope.
- `422`: Validation error
- `429`: Too many requests for this key. Wait for the `Retry-After` seconds.

---

[API](https://skmtc.dev/vocenya/apis/vocenya-api.md) · [All operations](https://skmtc.dev/vocenya/apis/vocenya-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vocenya/apis/vocenya-api/revisions/946913941565?raw)