---
title: "List Calls"
method: GET
path: "/v1/list-calls"
---

# List Calls

`GET /v1/list-calls`

Returns a paginated list of calls for the authenticated account, ordered by `triggered_at` descending. Optionally filter by `contact_id` to return only calls for a single contact, or by `agent_id` to return only calls for a single agent. `contact_id` and `agent_id` cannot be used together. Each item is a lean call payload: the response does not include a separate top-level `contact` object, and the `external_contact_id` and `contact_details` fields are omitted from each call (unlike [Get Call](/v1/endpoint/get-call)). Use the Contact endpoints if you need contact details.

## Query parameters

- `contact_id` string, uuid
- `agent_id` string, uuid
- `limit` integer
- `cursor` string

## Response `200`

Calls retrieved successfully

- object
  - `calls` object[] — Calls ordered by `triggered_at` descending
    - `call_id` string, uuid — Unique identifier for the call
    - `attempt` number — Which attempt number this call is within its loop
    - `from_number` string — Caller phone number in E.164 format
    - `to_number` string — Callee phone number in E.164 format
    - `direction` string — Call direction: 'inbound' or 'outbound'
    - `contact_id` string, uuid — telli contact ID
    - `agent_id` string, uuid — ID of the agent that handled the call
    - `triggered_at` number — Unix timestamp (ms) when the call was triggered
    - `triggered_at_iso` string — ISO 8601 timestamp when the call was triggered
    - `started_at` number — Unix timestamp (ms) when the call was answered
    - `started_at_iso` string — ISO 8601 timestamp when the call was answered
    - `ended_at` number — Unix timestamp (ms) when the call ended
    - `ended_at_iso` string — ISO 8601 timestamp when the call ended
    - `call_length_min` number — Duration of the call in minutes (rounded up)
    - `call_status` 'COMPLETED' | 'ANSWERED' | 'NOT_REACHED' | 'VOICEMAIL' | 'ERROR' — Deprecated. Use state, status, and follow_up instead.
    - `transcript` string — Plain text transcript of the call
    - `transcriptObject` union[] — Structured transcript as an array of messages
      - union
        - object
          - `role` 'user' | 'agent', required
          - `content` string, required
        - object
          - `role` 'agent', required
          - `toolActivity` string, required
          - `toolParameters` object
    - `call_analysis` object — AI-generated analysis of the call
    - `call_outcome` object — Structured outcome data extracted from the call
    - `collected_data` object — Data collected from the contact during the call via tasks
    - `booked_slot_for` string — ISO 8601 timestamp of the booked appointment slot, if any
    - `recording_url` string — URL to the call recording (only available when both parties have given consent)
    - `transfer` object, nullable — Transfer details when the call was transferred, or null if the call was not transferred
      - `destination` string — Transfer target the call was transferred to: an E.164 phone number or a tel:/sip: URI
      - `completed_at` string, nullable — ISO 8601 timestamp of when the call was transferred
    - `ended_reason` 'agent-ended-call' | 'agent-forwarded-call' | 'agent-busy' | 'agent-did-not-answer' | 'contact-busy' | 'contact-ended-call' | 'contact-did-not-answer' | 'phone-provider-closed-connection' | 'other' — Why the call ended
    - `state` 'queued' | 'ringing' | 'in_progress' | 'processing' | 'ended' — Current call lifecycle state
    - `status` 'connected' | 'not_connected' | 'voicemail' | 'failed', nullable — Normalized terminal connection status. Null while the call is not terminal.
    - `follow_up` object, nullable — Scheduled follow-up call information, if the agent scheduled one.
      - `type` 'agent_follow_up', required
      - `scheduled_at` string, date-time, required — When the follow-up call is scheduled
  - `next_cursor` string, nullable — Pass as `cursor` in the next request to fetch more results. `null` when there are no more pages.

## Other responses

- `400` — Invalid request - malformed UUID, invalid cursor, or `contact_id` and `agent_id` used together
- `401` — Unauthorized - Invalid API key

---

[API](https://skmtc.dev/telli/apis/telli-api.md) · [All operations](https://skmtc.dev/telli/apis/telli-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/telli/telli-api/revisions/9815a3c63c75/schema)