---
title: "Get a call"
method: GET
path: "/calls/{id}"
tags: ["calls"]
---

# Get a call

`GET /calls/{id}`

## Request

- Base URL: `https://api.voixcall.com/v1`
- URL: `https://api.voixcall.com/v1/calls/{id}`
- 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

One call by id. While the call is active, cost_so_far is set (counted from started_at, so it includes ring time until answered_at is recorded), and max_duration_seconds with credits:read. With expand[]=transcript (transcripts:read and the account setting "Allow connected apps to read call summaries"), transcript is the redacted summary-level transcript; when the setting is off the answer is 403 not_enabled with settings_url. A call that is not yours is not found. Requires calls:read.

## Path parameters

- `id` string, required: Call id (call_ prefix).

## Query parameters

- `expand[]` string[], nullable: expand[]=transcript adds the call's redacted summary-level transcript. Needs transcripts:read (else 403 insufficient_scope) and the account setting "Allow connected apps to read call summaries" (else 403 not_enabled with settings_url).

## Response `200`

OK

- CallDetail
  - `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.
  - `cost_so_far` string, nullable, required: Charge accrued so far, decimal string, only while status is active; null otherwise (including initiating and connecting). Counted from started_at, so it includes ring time until answered_at is recorded.
  - `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
  - `max_duration_seconds` integer, nullable, required: Time limit the balance allowed when the call was set up, while status is active. Derived from the balance, so it needs credits:read; null without it. Not recorded for app-placed personal calls today, so null for them.
  - `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` Transcript, required
    - `action_items` string[], nullable, required: Follow-ups from the call, redacted like summary.
    - `call_id` string, required
    - `completed_at` string, date-time, nullable, required
    - `duration_seconds` integer, nullable, required: Length of the transcribed recording.
    - `id` string, required
    - `language` string, nullable, required: BCP 47 tag when detected.
    - `livemode` boolean, required
    - `object` 'transcript', required: Always "transcript".
    - `reference_numbers` ReferenceNumber[], nullable, required: Facts worth copying out of the call (case ids, dates, amounts), redacted like summary with label and value checked together. An entry whose value was a sensitive number stays in the list with the value [redacted], so you know one was mentioned; the full value is only in the VoixCall app.
      - `label` string, required
      - `value` string, required
    - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'expired', required: pending and processing: being made. completed: summary available. failed: transcription failed (it can be requested again once it has stopped retrying). expired: removed by the transcript retention period; the summary and utterances are gone. New values may appear.
    - `summary` string, nullable, required: AI summary of the call, redacted: when it holds six or more digits in all, or a word such as code, OTP, PIN, password, card or account, every number in it reads [redacted]; keypad entries always do. null until completed, and once expired.
  - `transcript_status` 'pending' | 'processing' | 'completed' | 'failed' | 'null', nullable, required: null when no transcript was requested.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `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)