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

# List calls

`GET /calls`

## Request

- Base URL: `https://api.voixcall.com/v1`
- URL: `https://api.voixcall.com/v1/calls`
- Auth: one of:
  - OAuth 2 (authorization code, authorization URL `https://api.voixcall.com/oauth/authorize`, token URL `https://api.voixcall.com/oauth/token`, scopes: `calls:read`)
  - HTTP bearer

Calls on the personal account, newest first. counterparty_name is filled from contacts only with contacts:read. Organization calls are never included. Test keys get an empty list. Requires calls:read.

## Query parameters

- `limit` string: Page size, 1 to 100. Default 10.
- `starting_after` string: Return objects after this id (older).
- `ending_before` string: Return objects before this id (newer).
- `direction` 'outbound' | 'inbound': Only calls in this direction.
- `started_at[gte]` string: Only calls started at or after this RFC 3339 time.
- `started_at[lte]` string: Only calls started at or before this RFC 3339 time.
- `to` string: Only calls to this number, E.164 exact match.

## Response `200`

OK

- ListCall
  - `data` Call[], nullable, required
    - `answered_at` string, date-time, nullable, required: Not recorded for app calls today: null.
    - `cost` string, nullable, required: The recorded charge, decimal string with two decimals; null unless status is completed.
    - `counterparty_name` string, nullable, required: Name of the contact whose stored phone number exactly matches the other party (to_number outbound, from_number inbound); a contact saved in another format, such as with spaces, does not match. Requires contacts:read, else null.
    - `currency` 'USD', required
    - `direction` 'outbound' | 'inbound', required
    - `duration_seconds` integer, nullable, required: Billable seconds once the call has ended.
    - `ended_at` string, date-time, nullable, required
    - `from_number` string, required: E.164 caller ID used.
    - `id` string, required
    - `is_recorded` boolean, required
    - `livemode` boolean, required
    - `object` 'call', required: Always "call".
    - `origin` 'app' | 'api' | 'mcp', required: Which surface placed the call.
    - `placement` 'webrtc' | 'callback' | 'inbound', required: How the call was set up: from the app or browser (webrtc), by ringing your phone first (callback), or received on your number (inbound).
    - `rate_per_minute` string, required: The per-minute rate fixed at call setup and charged for this call, decimal string with four decimals.
    - `session` CallSession, required
      - `hangup_cause` string, nullable, required
      - `leg_a_status` string, required
      - `leg_b_status` string, required
      - `ring_number` string, required: The verified number that was rung.
    - `started_at` string, date-time, required
    - `status` string, required: initiating, connecting, active, completed, failed, no-answer, busy, canceled; callback calls add ringing_you and ringing_them. New values may appear.
    - `to_number` string, required: E.164.
    - `transcript_status` 'pending' | 'processing' | 'completed' | 'failed' | 'null', nullable, required: null when no transcript was requested.
  - `has_more` boolean, required: Whether more objects exist beyond this page in the direction of travel.
  - `object` 'list', required: Always "list".

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `429`: Too Many Requests
- `500`: Internal Server Error

---

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