---
title: "Get Call History"
method: GET
path: "/calling/history"
tags: ["calling"]
---

# Get Call History

`GET /calling/history`

Retrieves the history of calls made through the Ringg AI platform with optional filtering and pagination.

## Query parameters

- `start_date` string, date-time
- `end_date` string, date-time
- `limit` integer
- `offset` integer
- `agent_id` string
- `status` 'registered' | 'ongoing' | 'retry' | 'error' | 'completed' | 'failed' | 'cancelled' | 'forwarded'
- `bulk_list_id` string

## Headers

- `X-API-KEY` string, required

## Response `200`

Successful Response: Call history. Response format depends on download_format parameter.

- object
  - `calls` object[]
    - `id` string
    - `to_number` string
    - `name` string
    - `status` 'registered' | 'ongoing' | 'retry' | 'error' | 'completed' | 'failed' | 'cancelled' | 'forwarded' — The current status of the call
    - `sub_status` 'IN_DB' | 'QUEUED' | 'ACCEPTED' | 'RATE_LIMITED' | 'RETRY_LIMIT_REACHED' | 'RETRY_SCHEDULED' | 'FAILED' | 'USER_DID_NOT_JOIN' | 'USER_LEFT' | 'USER_BECAME_IDLE' | 'CAMPAIGN_TIME_EXCEEDED' | 'MAX_CALL_DURATION' | 'NOT_ABLE_TO_CALL' | 'USER_TERMINATED' | 'DND_SKIPPED' | 'VOICEMAIL_DETECTED' | 'VOICEMAIL_DETECTED_VIA_LLM' | 'PRE_CALL_API_FAILED' | 'RECONCILED_TO_ERROR_FROM_REGISTERED' | 'RECONCILED_TO_ERROR_FROM_RETRY' | 'RECONCILED_TO_ERROR_FROM_ONGOING' | 'RECONCILED_TO_COMPLETED_FROM_ONGOING' — The sub-status of the call providing more detail on the call outcome
    - `transcript` string
    - `audio_recording` string, uri — URL to the call recording. Valid for 24 hours after the call; download the recording within that window to retain it.
    - `created_at` string, date-time
    - `agent` object
      - `id` string
      - `agent_name` string
    - `call_duration` number
    - `call_attempt_time` string, date-time
    - `call_cost` number
    - `call_type` string
    - `inbound_from` string, nullable
  - `limit` integer
  - `offset` integer
  - `count` integer
  - `total` integer

## Other responses

- `400` — Bad Request - Invalid parameters or request format.
- `401` — Unauthorized - Invalid or missing API key.
- `500` — Internal Server Error - Something went wrong on our end.

---

[API](https://skmtc.dev/ringg/apis/ringg-ai-api-documentation.md) · [All operations](https://skmtc.dev/ringg/apis/ringg-ai-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ringg/ringg-ai-api-documentation/revisions/00b614a7714c/schema)