> ## Documentation Index > Fetch the complete documentation index at: https://docs.ringg.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get Call History > Retrieves the history of calls made through the Ringg AI platform with optional filtering and pagination. Retrieve call records for dashboards, support tools, exports, and reconciliation. This is the polling counterpart to webhooks. ## When to use * Show recent calls in your product. * Reconcile webhook events with stored call records. * Filter campaign results by `bulk_list_id`. * Debug a recipient's latest call status. ## Query guidance Use date ranges and pagination for production dashboards. Add filters such as `agent_id`, `status`, `call_type`, or `bulk_list_id` to keep responses focused. ## Production note Prefer webhooks for real-time workflows. Use call history for dashboards, backfills, and periodic consistency checks. ## OpenAPI ````yaml get /calling/history openapi: 3.0.0 info: title: Ringg AI API Documentation description: >- This is the documentation for the Ringg AI APIs. The Ringg AI API follows RESTful principles, making it intuitive and easy to integrate with your applications. All API requests should be made to the base URL. The API accepts and returns data in JSON format. Ensure your requests include the appropriate Content-Type header for POST and PATCH requests. version: 2.0.0 servers: - url: https://prod-api.ringg.ai/ca/api/v0 security: [] tags: - name: workspace description: Endpoints for managing your workspace. - name: agent description: Endpoints for managing assistants (agents). - name: calling description: Endpoints for making and managing calls. - name: campaign description: Endpoints for managing campaigns. - name: analytics description: Endpoints for accessing call analytics and performance metrics. - name: termination description: Endpoints for terminating active calls using different methods. - name: knowledgebase description: Endpoints for managing knowledge bases. paths: /calling/history: get: tags: - calling summary: Get Call History description: >- Retrieves the history of calls made through the Ringg AI platform with optional filtering and pagination. operationId: getCallHistory parameters: - name: X-API-KEY in: header description: (Required) Your Ringg AI API key. required: true schema: type: string example: 7251cb4b-3373-43a4-844c-b27a1d45e0c9 - name: start_date in: query description: >- Filter calls starting from this date (ISO 8601 format with timezone). schema: type: string format: date-time default: '2025-09-25T00:00:00+05:30' example: '2025-09-25T00:00:00+05:30' - name: end_date in: query description: Filter calls up to this date (ISO 8601 format with timezone). schema: type: string format: date-time default: '2025-09-25T23:59:59+05:30' example: '2025-09-25T23:59:59+05:30' - name: limit in: query description: 'Maximum number of calls to return (default: 10).' schema: type: integer default: 10 example: 50 - name: offset in: query description: 'Number of calls to skip (default: 0).' schema: type: integer default: 0 example: 20 - name: agent_id in: query description: Filter calls by assistant ID. schema: type: string example: 830f767a-397e-4b39-82ff-235cd344e2f9 - name: status in: query description: Filter calls by status. schema: type: string enum: - registered - ongoing - retry - error - completed - failed - cancelled - forwarded example: completed - name: bulk_list_id in: query description: Filter calls by bulk list ID. schema: type: string example: 123e4567-e89b-12d3-a456-426614174000 responses: '200': description: >- Successful Response: Call history. Response format depends on download_format parameter. content: application/json: schema: type: object properties: calls: type: array items: type: object properties: id: type: string to_number: type: string name: type: string status: type: string description: The current status of the call enum: - registered - ongoing - retry - error - completed - failed - cancelled - forwarded sub_status: type: string description: >- The sub-status of the call providing more detail on the call outcome enum: - 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 transcript: type: string audio_recording: type: string format: uri description: >- URL to the call recording. Valid for 24 hours after the call; download the recording within that window to retain it. created_at: type: string format: date-time agent: type: object properties: id: type: string agent_name: type: string call_duration: type: number call_attempt_time: type: string format: date-time call_cost: type: number call_type: type: string inbound_from: type: string nullable: true limit: type: integer offset: type: integer count: type: integer total: type: integer examples: regular_response: summary: Regular call history (download=false) value: calls: - id: 34a29572-9e09-453d-bcb8-90cdbb157c79 to_number: '+918882876897' name: abhishek status: completed sub_status: ACCEPTED transcript: >- [{"bot": "Hi there! I'm Marcel from sdfasd. We're conducting a brief survey about asdfasdf to improve our services. Your feedback"}, {"bot": "is valuable to us."}] audio_recording: >- https://aps1.media.plivo.com/v1/Account/MAZJNLNJIYNWMZYZHIMM/Recording/e99c9f6b-1d1e-4290-857d-1524d8204aad.mp3 created_at: '2025-11-24T11:37:43.678043+00:00' agent: id: 5d7cdc09-6d51-4468-93c6-a0b8e5ad3f22 agent_name: test after prod agent_version_id: 387bd8f1-5748-4006-b7fe-6a6455e9d45d orchestration_mode: single_node version: version_id: 387bd8f1-5748-4006-b7fe-6a6455e9d45d 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: - '+912269976804' voicemail_detected: false limit: 10 offset: 0 count: 1 total: 1 '400': description: Bad Request - Invalid parameters or request format. content: application/json: schema: type: object properties: error: type: object properties: code: type: string example: invalid_parameter message: type: string example: Invalid date format for start_date. '401': description: Unauthorized - Invalid or missing API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string example: 401 Unauthorized message: type: string example: Invalid credentials '500': description: Internal Server Error - Something went wrong on our end. content: application/json: schema: type: object properties: error: type: object properties: code: type: string example: 500 Internal Server Error message: type: string example: An unexpected error occurred on the server. x-code-samples: - lang: curl label: cURL source: |- 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=830f767a-397e-4b39-82ff-235cd344e2f9&status=completed&bulk_list_id=123e4567-e89b-12d3-a456-426614174000' \ --header 'X-API-KEY: ' ````