> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravan.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone Call History

> Returns all calls where a phone number appears as caller or callee, with cost and credit details and optional transcripts.

### Authorizations

<ParamField header="Authorization" type="string">
  Bearer JWT used to authenticate the request.
</ParamField>

<ParamField header="X-Api-Key" type="string">
  Org API key. You can use this instead of JWT.
</ParamField>

***

### Query Parameters

<ParamField query="phone" type="string" required>
  Phone number in E.164 format. Example: `+1234567890`.
</ParamField>

<ParamField query="page" type="integer">
  Page number to return. Defaults to `1`.
</ParamField>

<ParamField query="page_size" type="integer">
  Results per page. Defaults to `20` and maximum is `100`.
</ParamField>

<ParamField query="include_transcripts" type="boolean">
  Set to `true` to include transcripts in each call result.
</ParamField>

***

### Response

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message.
</ResponseField>

<ResponseField name="phone" type="string">
  The phone number used for the lookup.
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total number of matching calls.
</ResponseField>

<ResponseField name="page" type="integer">
  Current page number.
</ResponseField>

<ResponseField name="page_size" type="integer">
  Number of results returned per page.
</ResponseField>

<ResponseField name="calls" type="array">
  Matching calls.

  <Expandable title="calls[]">
    <ResponseField name="id" type="string">
      Call session UUID.
    </ResponseField>

    <ResponseField name="agent_id" type="string">
      Agent UUID.
    </ResponseField>

    <ResponseField name="agent_name" type="string">
      Agent name.
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization UUID.
    </ResponseField>

    <ResponseField name="caller_number" type="string">
      Caller phone number.
    </ResponseField>

    <ResponseField name="callee_number" type="string">
      Callee phone number.
    </ResponseField>

    <ResponseField name="caller_name" type="string">
      Caller name.
    </ResponseField>

    <ResponseField name="caller_email" type="string">
      Caller email.
    </ResponseField>

    <ResponseField name="channel" type="string">
      Call channel.
    </ResponseField>

    <ResponseField name="status" type="string">
      Call status.
    </ResponseField>

    <ResponseField name="summary" type="string">
      Call summary.
    </ResponseField>

    <ResponseField name="recording_url" type="string">
      Recording URL.
    </ResponseField>

    <ResponseField name="duration_sec" type="integer">
      Call duration in seconds.
    </ResponseField>

    <ResponseField name="cost_total" type="string">
      Total call cost.
    </ResponseField>

    <ResponseField name="twilio_cost" type="number">
      Telephony provider cost.
    </ResponseField>

    <ResponseField name="model_cost" type="number">
      Model cost.
    </ResponseField>

    <ResponseField name="credit_breakdown" type="object">
      Credit usage breakdown.
    </ResponseField>

    <ResponseField name="disconnect_reason" type="string">
      Disconnect reason.
    </ResponseField>

    <ResponseField name="call_latency_ms" type="integer">
      Call latency in milliseconds.
    </ResponseField>

    <ResponseField name="error_message" type="string">
      Error message, if any.
    </ResponseField>

    <ResponseField name="post_call_analysis_result" type="object">
      Post-call analysis result.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Custom metadata.
    </ResponseField>

    <ResponseField name="started_at" type="string">
      Start timestamp.
    </ResponseField>

    <ResponseField name="ended_at" type="string">
      End timestamp.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Creation timestamp.
    </ResponseField>

    <ResponseField name="transcripts" type="array">
      Transcript entries when requested.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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"
          }
        ]
      }
    ]
  }
  ```
</ResponseExample>


## OpenAPI

````yaml GET /api/v1/calling/phone-history
openapi: 3.0.1
info:
  title: Agni API
  version: 1.0.0
  description: >-
    Agni API for managing agents, tools, widget settings, telephony, and
    integrations.
servers:
  - url: https://api.ravan.ai
security:
  - X-Api-Key: []
tags:
  - name: AgentService
  - name: AgentToolService
  - name: WidgetSettingsService
  - name: PhoneService
  - name: AppointmentService
  - name: GHLService
  - name: CalComService
  - name: CampaignService
  - name: ContactService
  - name: CallingService
  - name: RAGService
  - name: ModelService
  - name: HealthService
paths:
  /api/v1/calling/phone-history:
    get:
      tags:
        - CallingService
      summary: Get Phone Call History
      description: >-
        Returns all calls where a phone number appears as caller or callee, with
        cost and credit details and optional transcripts.
      operationId: GetPhoneCallHistory
      parameters:
        - name: phone
          in: query
          required: true
          schema:
            type: string
          description: 'Phone number in E.164 format. Example: +1234567890.'
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          description: Page number. Defaults to 1.
        - name: page_size
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
          description: Results per page. Defaults to 20. Maximum 100.
        - name: include_transcripts
          in: query
          schema:
            type: boolean
          description: Set to true to include transcripts in each call result.
      responses:
        '200':
          description: call history retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneHistoryResponse'
              example:
                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
                    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'
        '400':
          description: Missing phone param or invalid organization id
        '401':
          description: Authentication required
        '500':
          description: Query failure
      security:
        - BearerAuth: []
        - X-Api-Key: []
components:
  schemas:
    PhoneHistoryResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: call history retrieved successfully
        phone:
          type: string
          example: '+919876543210'
        total_count:
          type: integer
          example: 3
        page:
          type: integer
          example: 1
        page_size:
          type: integer
          example: 20
        calls:
          type: array
          items:
            $ref: '#/components/schemas/PhoneHistoryCall'
    PhoneHistoryCall:
      type: object
      properties:
        id:
          type: string
          format: uuid
        agent_id:
          type: string
          format: uuid
        agent_name:
          type: string
        organization_id:
          type: string
          format: uuid
        caller_number:
          type: string
        callee_number:
          type: string
        caller_name:
          type: string
        caller_email:
          type: string
        channel:
          type: string
        status:
          type: string
        summary:
          type: string
        recording_url:
          type: string
        duration_sec:
          type: integer
          example: 250
        cost_total:
          type: string
          example: '12.50'
        twilio_cost:
          type: number
          example: 5.1
        model_cost:
          type: number
          example: 4.2
        credit_breakdown:
          $ref: '#/components/schemas/PhoneHistoryCreditBreakdown'
        disconnect_reason:
          type: string
        call_latency_ms:
          type: integer
          example: 820
        error_message:
          type: string
        post_call_analysis_result:
          type: object
          additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
        started_at:
          type: string
          format: date-time
        ended_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        transcripts:
          type: array
          items:
            $ref: '#/components/schemas/PhoneHistoryTranscript'
    PhoneHistoryCreditBreakdown:
      type: object
      properties:
        model_credits:
          type: number
          example: 4.2
        provider_credits:
          type: number
          example: 5.1
        telephony_base_credits:
          type: number
          example: 4
    PhoneHistoryTranscript:
      type: object
      properties:
        id:
          type: string
          format: uuid
        call_session_id:
          type: string
          format: uuid
        message:
          $ref: '#/components/schemas/PhoneHistoryTranscriptMessage'
        timestamp_ms:
          type: integer
          format: int64
          example: 1765437000123
        created_at:
          type: string
          format: date-time
    PhoneHistoryTranscriptMessage:
      type: object
      properties:
        role:
          type: string
          example: agent
        content:
          type: string
          example: Hello!
  securitySchemes:
    X-Api-Key:
      type: apiKey
      in: header
      name: X-Api-Key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````