Get Call History

cURL

curl --request GET \
  --url 'https://prod-api.ringg.ai/ca/api/v0/calling/history?start_date=2025-09-25T00:00:00%2B05:30&end_date=2025-09-25T23:59:59%2B05:30&limit=50&offset=20&agent_id=00000000-0000-4000-8000-0000000000a1&status=completed&bulk_list_id=123e4567-e89b-12d3-a456-426614174000' \
  --header 'X-API-KEY: <x-api-key>'

const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://prod-api.ringg.ai/ca/api/v0/calling/history', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "calls": [
    {
      "id": "00000000-0000-4000-8000-00000000010a",
      "to_number": "+919876543210",
      "name": "Priya",
      "status": "completed",
      "sub_status": "ACCEPTED",
      "transcript": "[{\"bot\": \"Hi Priya, this is Asha from Acme Lending. Is this a good time to talk about your EMI due on 5 October?\"}, {\"user\": \"Yes, go ahead.\"}]",
      "audio_recording": "https://example.com/recordings/call-123.mp3",
      "created_at": "2025-11-24T11:37:43.678043+00:00",
      "agent": {
        "id": "00000000-0000-4000-8000-000000000108",
        "agent_name": "Payment reminder",
        "agent_version_id": "00000000-0000-4000-8000-0000000000d1",
        "orchestration_mode": "single_node",
        "version": {
          "version_id": "00000000-0000-4000-8000-0000000000d1",
          "version_slug": "v1"
        }
      },
      "call_duration": 7.98,
      "call_attempt_time": "2025-11-24T11:37:48.549486+00:00",
      "call_cost": 0.2,
      "call_type": "outbound",
      "inbound_from": null,
      "credits_processed": true,
      "from_numbers": [
        "+919876500000"
      ],
      "voicemail_detected": false
    }
  ],
  "limit": 10,
  "offset": 0,
  "count": 1,
  "total": 1
}

{
  "message": "Limit cannot be greater than 200"
}

{
  "message": "Invalid credentials"
}

{
  "message": "<string>"
}

{
  "message": "An unexpected error occurred. Please try again later."
}

GET

calling

history

cURL

curl --request GET \
  --url 'https://prod-api.ringg.ai/ca/api/v0/calling/history?start_date=2025-09-25T00:00:00%2B05:30&end_date=2025-09-25T23:59:59%2B05:30&limit=50&offset=20&agent_id=00000000-0000-4000-8000-0000000000a1&status=completed&bulk_list_id=123e4567-e89b-12d3-a456-426614174000' \
  --header 'X-API-KEY: <x-api-key>'

const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://prod-api.ringg.ai/ca/api/v0/calling/history', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "calls": [
    {
      "id": "00000000-0000-4000-8000-00000000010a",
      "to_number": "+919876543210",
      "name": "Priya",
      "status": "completed",
      "sub_status": "ACCEPTED",
      "transcript": "[{\"bot\": \"Hi Priya, this is Asha from Acme Lending. Is this a good time to talk about your EMI due on 5 October?\"}, {\"user\": \"Yes, go ahead.\"}]",
      "audio_recording": "https://example.com/recordings/call-123.mp3",
      "created_at": "2025-11-24T11:37:43.678043+00:00",
      "agent": {
        "id": "00000000-0000-4000-8000-000000000108",
        "agent_name": "Payment reminder",
        "agent_version_id": "00000000-0000-4000-8000-0000000000d1",
        "orchestration_mode": "single_node",
        "version": {
          "version_id": "00000000-0000-4000-8000-0000000000d1",
          "version_slug": "v1"
        }
      },
      "call_duration": 7.98,
      "call_attempt_time": "2025-11-24T11:37:48.549486+00:00",
      "call_cost": 0.2,
      "call_type": "outbound",
      "inbound_from": null,
      "credits_processed": true,
      "from_numbers": [
        "+919876500000"
      ],
      "voicemail_detected": false
    }
  ],
  "limit": 10,
  "offset": 0,
  "count": 1,
  "total": 1
}

{
  "message": "Limit cannot be greater than 200"
}

{
  "message": "Invalid credentials"
}

{
  "message": "<string>"
}

{
  "message": "An unexpected error occurred. Please try again later."
}

Webhooks are the better fit for reacting to each call as it ends (Event Subscription); use this endpoint for dashboards, backfills and checking that no webhook was missed.

Notes

start_date and end_date take a timezone offset, for example 2026-10-01T00:00:00+05:30. bulk_list_id is the campaign’s ID. status is one of registered, ongoing, retry, error, completed, failed, cancelled, forwarded. Repeat agent_id, status or bulk_list_id to filter by several values.
limit defaults to 10; more than 200 returns 400. Page with offset.
The list allows 10 requests per workspace per minute; more return 429.
transcript is a JSON-encoded string; parse it to get the turns.
The response’s total is the number of calls matching the filters, for paging.
audio_recording links may expire. Fetch a fresh link from Get call details, and download recordings you need to keep.
For one call with its post-call analysis, use Get call details. To get many calls as a CSV by email, use Download call history.

Authorizations

X-API-KEY

string

header

required

Headers

X-API-KEY

string

required

(Required) Your Ringg AI API key.

Example:

"rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Query Parameters

start_date

string<date-time>

Filter calls starting from this date (ISO 8601 format with timezone).

Example:

"2025-09-25T00:00:00+05:30"

end_date

string<date-time>

Filter calls up to this date (ISO 8601 format with timezone).

Example:

"2025-09-25T23:59:59+05:30"

limit

integer

default:10

Maximum number of calls to return. More than 200 returns 400.

Required range: x <= 200

Example:

50

offset

integer

default:0

Number of calls to skip (default: 0).

Example:

20

agent_id

string[]

Filter by agent ID. Repeat the parameter to filter by several agents.

Example:

["00000000-0000-4000-8000-0000000000a1"]

status

enum<string>[]

Filter by call status. Repeat the parameter to filter by several.

Available options:

registered,

ongoing,

retry,

error,

completed,

failed,

cancelled,

forwarded

Example:

["completed"]

bulk_list_id

string[]

Filter by campaign (bulk_list_id). Repeat the parameter to filter by several campaigns.

Example:

["123e4567-e89b-12d3-a456-426614174000"]

version_id

string[]

Filter by agent version ID. Repeat the parameter to filter by several.

call_type

enum<string>

Filter by call type. callback and voicemail match calls of any direction that were callbacks or reached voicemail.

Available options:

inbound,

outbound,

webcall,

callback,

voicemail

Example:

"outbound"

from_number

string

Filter by caller number.

Example:

"+919876540001"

to_number

string

Filter by the number called.

Example:

"+919876543210"

call_id

string

Return only this call (UUID).

sort_by

enum<string>

default:call_time

Field to sort by.

Available options:

call_time,

created_at,

called_on_time,

call_duration,

credits_used,

retry_count

sort_order

enum<string>

Sort direction.

Available options:

asc,

desc

Response

Successful Response: Call history.

calls

object[]

Show child attributes

limit

integer

offset

integer

count

integer

total

integer

Introduction

Agents

Inventory

Calling

Monitoring

Account

Notes

Authorizations

Headers

Query Parameters

Response

​Notes

Authorizations

Headers

Query Parameters

Response

Notes