---
title: "List call history"
method: GET
path: "/call-history"
tags: ["Call History"]
---

# List call history

`GET /call-history`

Retrieve a paginated list of call history records for the authenticated organization.

**Polling integrations (e.g. Zapier):** to avoid missing calls during high-volume windows, poll with `sort=-created_at&created_after=<bookmark>`, where `<bookmark>` is the highest `created_at` value seen in the previous batch. Results are returned in `created_at DESC, id DESC` order by default, so pagination is deterministic.

## Query parameters

- `limit` integer — Maximum number of call records to return
- `offset` integer — Number of call records to skip for pagination
- `sort` string, nullable — Sort field. Prefix with '-' for descending order. Available: start_time, end_time, duration, created_at
- `call_status` string, nullable — Filter by call status. Accepted values: Completed, Not Answered, Rejected, Failed, Busy, Voicemail, Ended In Queue
- `is_outbound` boolean, nullable — Filter by call direction (true for outbound, false for inbound)
- `from_number` string, nullable — Filter by caller phone number
- `to_number` string, nullable — Filter by called phone number
- `phone_number` string, nullable — Filter by any phone number (from_number or to_number)
- `contact_id` string, uuid, nullable — Filter by contact ID
- `created_after` string, date-time, nullable — Return only calls created strictly after this ISO-8601 timestamp. Intended for polling integrations: bookmark the highest `created_at` from the previous response and pass it back on the next request to fetch only new calls.

## Response `200`

Successfully retrieved call history

- object
  - `ok` boolean
  - `data` object[]
    - `id` string, uuid
    - `created_at` string, date-time
    - `is_outbound` boolean
    - `status` string
    - `user_id` string, uuid
    - `from_number` string
    - `to_number` string
    - `duration` integer
    - `start_time` string, date-time
    - `end_time` string, date-time
    - `reason` string
    - `hangup_reason` string
    - `agent` object
      - `id` string, uuid
      - `name` string
      - `agent_type` string
    - `criteria_status` string
    - `customer_contact` object
      - `id` string, uuid
      - `first_name` string
      - `last_name` string
      - `phone_number` string
      - `email` string, email
      - `address` string
    - `recording_url` string
    - `recording_file_id` string, uuid
    - `recording_duration` integer
  - `meta` object
    - `limit` integer
    - `offset` integer
    - `total_items` integer

## Other responses

- `401` — Invalid or missing API key
- `403` — Insufficient permissions

---

[API](https://skmtc.net/yourang/apis/yourang-ai-external-api-v1.md) · [All operations](https://skmtc.net/yourang/apis/yourang-ai-external-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yourang/yourang-ai-external-api-v1/versions/49680ee64400/schema)