Skip to main content
GET
/
api
/
v1
/
calling
/
phone-history
Get Phone Call History
curl --request GET \
  --url https://api.ravan.ai/api/v1/calling/phone-history \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "message": "call history retrieved successfully",
  "phone": "+919876543210",
  "total_count": 3,
  "page": 1,
  "page_size": 20,
  "calls": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "agent_id": "8f14e45f-ceea-467f-a1d1-91ad4fb0e6c4",
      "agent_name": "Support Agent",
      "organization_id": "0b2c1d3e-4f56-4789-9abc-def012345678",
      "caller_number": "+14155550100",
      "callee_number": "+919876543210",
      "caller_name": "Jane Doe",
      "caller_email": "jane@example.com",
      "channel": "phone",
      "status": "completed",
      "summary": "Customer asked about billing.",
      "recording_url": "https://api.example.com/api/v1/calling/sessions/550e8400-e29b-41d4-a716-446655440000/recording",
      "duration_sec": 250,
      "cost_total": "12.50",
      "twilio_cost": 5.1,
      "model_cost": 4.2,
      "credit_breakdown": {
        "model_credits": 4.2,
        "provider_credits": 5.1,
        "telephony_base_credits": 4.0
      },
      "disconnect_reason": "user_hangup",
      "call_latency_ms": 820,
      "error_message": "",
      "post_call_analysis_result": {
        "sentiment": "positive"
      },
      "metadata": {
        "source": "crm"
      },
      "started_at": "2026-06-11T09:30:00Z",
      "ended_at": "2026-06-11T09:34:10Z",
      "created_at": "2026-06-11T09:29:58Z",
      "transcripts": [
        {
          "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
          "call_session_id": "550e8400-e29b-41d4-a716-446655440000",
          "message": {
            "role": "agent",
            "content": "Hello!"
          },
          "timestamp_ms": 1765437000123,
          "created_at": "2026-06-11T09:30:01Z"
        }
      ]
    }
  ]
}

​
Authorizations

​
Authorization
string
Bearer JWT used to authenticate the request.
​
X-Api-Key
string
Org API key. You can use this instead of JWT.

​
Query Parameters

​
phone
string
required
Phone number in E.164 format. Example: +1234567890.
​
page
integer
Page number to return. Defaults to 1.
​
page_size
integer
Results per page. Defaults to 20 and maximum is 100.
​
include_transcripts
boolean
Set to true to include transcripts in each call result.

​
Response

​
success
boolean
Whether the request succeeded.
​
message
string
Human-readable status message.
​
phone
string
The phone number used for the lookup.
​
total_count
integer
Total number of matching calls.
​
page
integer
Current page number.
​
page_size
integer
Number of results returned per page.
​
calls
array
Matching calls.
{
  "success": true,
  "message": "call history retrieved successfully",
  "phone": "+919876543210",
  "total_count": 3,
  "page": 1,
  "page_size": 20,
  "calls": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "agent_id": "8f14e45f-ceea-467f-a1d1-91ad4fb0e6c4",
      "agent_name": "Support Agent",
      "organization_id": "0b2c1d3e-4f56-4789-9abc-def012345678",
      "caller_number": "+14155550100",
      "callee_number": "+919876543210",
      "caller_name": "Jane Doe",
      "caller_email": "jane@example.com",
      "channel": "phone",
      "status": "completed",
      "summary": "Customer asked about billing.",
      "recording_url": "https://api.example.com/api/v1/calling/sessions/550e8400-e29b-41d4-a716-446655440000/recording",
      "duration_sec": 250,
      "cost_total": "12.50",
      "twilio_cost": 5.1,
      "model_cost": 4.2,
      "credit_breakdown": {
        "model_credits": 4.2,
        "provider_credits": 5.1,
        "telephony_base_credits": 4.0
      },
      "disconnect_reason": "user_hangup",
      "call_latency_ms": 820,
      "error_message": "",
      "post_call_analysis_result": {
        "sentiment": "positive"
      },
      "metadata": {
        "source": "crm"
      },
      "started_at": "2026-06-11T09:30:00Z",
      "ended_at": "2026-06-11T09:34:10Z",
      "created_at": "2026-06-11T09:29:58Z",
      "transcripts": [
        {
          "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
          "call_session_id": "550e8400-e29b-41d4-a716-446655440000",
          "message": {
            "role": "agent",
            "content": "Hello!"
          },
          "timestamp_ms": 1765437000123,
          "created_at": "2026-06-11T09:30:01Z"
        }
      ]
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
phone
string
required

Phone number in E.164 format. Example: +1234567890.

​
page
integer
default:1

Page number. Defaults to 1.

​
page_size
integer
default:20

Results per page. Defaults to 20. Maximum 100.

Required range: x <= 100
​
include_transcripts
boolean

Set to true to include transcripts in each call result.

Response

call history retrieved successfully

​
success
boolean
Example:

true

​
message
string
Example:

"call history retrieved successfully"

​
phone
string
Example:

"+919876543210"

​
total_count
integer
Example:

3

​
page
integer
Example:

1

​
page_size
integer
Example:

20

​
calls
object[]