---
title: "List phone calls"
method: GET
path: "/v1/voice/calls"
tags: ["Voice"]
---

# List phone calls

`GET /v1/voice/calls`

Your PSTN voice calls (inbound + outbound), newest first. Cursor
pagination: pass the returned `nextCursor` as `before` for the next
page. For a history that also includes WhatsApp calls, use
`GET /v1/calls`.

## Query parameters

- `status` 'ringing' | 'answered' | 'ended' | 'failed'
- `direction` 'inbound' | 'outbound'
- `number` string
- `before` string, date-time
- `limit` integer

## Response `200`

Calls, newest first

- object
  - `calls` CallRecord[]
    - `_id` string
    - `accountId` string — Owning social account. The unified /v1/calls/{id} detail + recording endpoints work for any channel; the channel-specific endpoints remain for account-scoped access.
    - `conversationId` string, nullable — Inbox conversation with the counterparty, when one exists.
    - `contactId` string, nullable — CRM Contact for the counterparty, when resolved.
    - `channel` 'whatsapp' | 'pstn'
    - `direction` 'inbound' | 'outbound'
    - `from` string — Caller number (E.164).
    - `to` string — Callee number (E.164).
    - `forwardTo` string, nullable — Destination the call was routed to (tel:/sip:/wss:), snapshotted at routing time.
    - `greeting` string, nullable — Outbound PSTN only. Message spoken to the callee on answer, before the bridge.
    - `status` 'ringing' | 'answered' | 'ended' | 'failed'
    - `isVoicemail` boolean — True when an inbound call went to voicemail.
    - `amd` boolean — Outbound answering-machine detection was requested for this call.
    - `answeredMachine` boolean, nullable — With `amd`, whether a machine (vs a human) answered.
    - `forwardCallerId` 'business' | 'caller' — Caller ID presented on the forwarded leg.
    - `recordingEnabled` boolean — Effective flag for THIS call (number default + per-call override, resolved at create time).
    - `transcriptionEnabled` boolean
    - `transcriptionLanguage` 'auto' | 'en' | 'es'
    - `startedAt` string, date-time
    - `answeredAt` string, date-time, nullable
    - `endedAt` string, date-time, nullable
    - `transferredAt` string, date-time, nullable — When the call was blind-transferred (POST /v1/voice/calls/{id}/transfer).
    - `durationSeconds` integer
    - `endReason` 'hangup' | 'no_answer' | 'rejected' | 'error'
    - `hangupCause` string, nullable — Raw carrier hangup cause behind endReason (e.g. normal_clearing, not_found, time_limit) — the actual motive when endReason is a coarse bucket.
    - `sipHangupCause` string, nullable — SIP response code that ended the call, when SIP-signalled (e.g. '403', '488'). The real failure reason for SIP legs.
    - `callErrors` object[] — Per-call failure log (dial failed, bridge failed, recording error).
      - `code` integer
      - `message` string
    - `recordingUrl` string, nullable — May be expired. Resolve a fresh playable URL via GET /v1/calls/{id}/recording (any channel).
    - `lastTranscriptSnippet` string, nullable — Most recent transcript segment, for list previews.
    - `transcript` object[] — Full transcript segments (detail endpoint only; omitted from lists).
      - `text` string
      - `confidence` number
      - `at` string, date-time
    - `billing` object
      - `metaMinutes` number
      - `telnyxSeconds` number
      - `transcriptionSeconds` number
      - `transcriptionCostUSD` number
      - `metaCostUSD` number — WhatsApp channel only. Meta per-minute charge, billed by Meta directly to your WABA. Display only; not billed by Zernio.
      - `telnyxCostUSD` number
      - `recordingCostUSD` number
      - `billableCostUSD` number — Amount Zernio bills you = telephony leg + recording + transcription (excludes any Meta portion).
      - `totalCostUSD` number — Full cost incl. any Meta portion you pay directly. Display only.
      - `currency` string
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
  - `nextCursor` string, date-time, nullable

## Other responses

- `401` — Unauthorized

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/versions/51932b099b2f/schema)