> ## 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. > ## Agent Instructions > To search or read these docs, connect the Ringg docs MCP server at https://docs.ringg.ai/mcp (no key needed; tools search_ringg_ai and query_docs_filesystem_ringg_ai) instead of browsing pages one by one. Setup for each client: https://docs.ringg.ai/resources/mcp-server/docs-mcp-server/mcp-for-ai-assistants.md > The dashboard labels agents "Assistants"; these docs say "agent". Both mean the same object, identified by agent_id. > API base URL: https://prod-api.ringg.ai/ca/api/v0. Send the workspace API key in the X-API-KEY header, from server-side code only. > Placing a call dials a real phone number and spends credits. Confirm the number with the user before calling. > To act on a Ringg workspace (place calls, edit agents, read transcripts), use the separate Ringg workspace MCP server at https://mcp.ringg.ai/mcp: https://docs.ringg.ai/resources/mcp-server/workspace-mcp-server/overview.md > List calls in your workspace by date range, agent, status or campaign, with transcript, recording link, duration and cost, to reconcile results or backfill. # Get Call History export const RelatedTopics = ({items}) =>
Related topics
{items.map(([title, href]) => {title} )}
; Webhooks are the better fit for reacting to each call as it ends ([Event Subscription](/documentation/build-agents/customize-agent-behaviour/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](/api-reference/monitoring/call-history/get-call-details), and download recordings you need to keep. * For one call with its post-call analysis, use [Get call details](/api-reference/monitoring/call-history/get-call-details). To get many calls as a CSV by email, use [Download call history](/api-reference/monitoring/call-history/download-call-history). ## OpenAPI ````yaml get /calling/history openapi: 3.0.0 info: title: Ringg AI API Documentation description: >- The Ringg AI REST API. Base URL https://prod-api.ringg.ai/ca/api/v0; send your workspace API key in the X-API-KEY header from server-side code only. Requests and responses are JSON. version: 2.0.0 contact: name: Ringg AI support email: admin@ringg.ai url: https://docs.ringg.ai 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 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: rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx - name: start_date in: query description: >- Filter calls starting from this date (ISO 8601 format with timezone). schema: type: string format: date-time 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 example: '2025-09-25T23:59:59+05:30' - name: limit in: query description: Maximum number of calls to return. More than 200 returns 400. schema: type: integer default: 10 maximum: 200 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 by agent ID. Repeat the parameter to filter by several agents. schema: type: array items: type: string example: - 00000000-0000-4000-8000-0000000000a1 - name: status in: query description: Filter by call status. Repeat the parameter to filter by several. schema: type: array items: type: string enum: - registered - ongoing - retry - error - completed - failed - cancelled - forwarded example: - completed - name: bulk_list_id in: query description: >- Filter by campaign (`bulk_list_id`). Repeat the parameter to filter by several campaigns. schema: type: array items: type: string example: - 123e4567-e89b-12d3-a456-426614174000 - name: version_id in: query description: >- Filter by agent version ID. Repeat the parameter to filter by several. schema: type: array items: type: string - name: call_type in: query description: >- Filter by call type. `callback` and `voicemail` match calls of any direction that were callbacks or reached voicemail. schema: type: string enum: - inbound - outbound - webcall - callback - voicemail example: outbound - name: from_number in: query description: Filter by caller number. schema: type: string example: '+919876540001' - name: to_number in: query description: Filter by the number called. schema: type: string example: '+919876543210' - name: call_id in: query description: Return only this call (UUID). schema: type: string - name: sort_by in: query description: Field to sort by. schema: type: string enum: - call_time - created_at - called_on_time - call_duration - credits_used - retry_count default: call_time - name: sort_order in: query description: Sort direction. schema: type: string enum: - asc - desc responses: '200': description: 'Successful Response: Call history.' 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: >- `registered`: created, not dialled yet (queued, scheduled, outside calling hours or held by a call limit). `ongoing`: dialling, ringing or in conversation. `retry`: an attempt did not connect and another is scheduled. `completed`: connected and ended, including voicemail detected. `failed`: no conversation and nothing left to try, such as busy or unanswered on the last attempt, a DND number, or the campaign window ending first. `error`: a system-side failure, such as the dial or the pre-call API failing. `cancelled`: stopped on purpose, by Terminate calls, a passed deadline or a call limit. `forwarded`: an inbound call sent to the agent's transfer number by its inbound rate limit. enum: - registered - ongoing - retry - error - completed - failed - cancelled - forwarded sub_status: type: string description: >- The detail behind `call_status`. Examples: `FREQUENCY_DEFERRED` (held by a call limit), `FREQUENCY_CAPPED` (cancelled by a call limit), `DEADLINE_PASSED` (cancelled at `call_deadline` or `call_validity_hours`), `USER_TERMINATED` (Terminate calls), `DND_SKIPPED`, `RETRY_LIMIT_REACHED`. For a failed or error call, webhooks and exports can carry the carrier's own reason instead. 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 - FREQUENCY_DEFERRED - FREQUENCY_CAPPED - FREQUENCY_CHECK_FAILED - DEADLINE_PASSED - PHONOS_TIMEOUT transcript: type: string description: >- The transcript as a JSON-encoded string; parse it to get one object per turn. audio_recording: type: string format: uri description: >- URL of the call recording. The link may expire; fetch a fresh one from Get Call Details. 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: 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 '400': description: >- Bad Request - For example, `limit` over 200 or an ID that is not a UUID. content: application/json: schema: type: object properties: message: type: string example: Limit cannot be greater than 200 '401': description: Unauthorized - Invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Invalid credentials '429': description: >- Too Many Requests - More than 10 list requests in 60 seconds from one workspace. content: application/json: schema: type: object properties: message: type: string '500': description: Internal Server Error - Something went wrong on our end. content: application/json: schema: type: object properties: message: type: string example: An unexpected error occurred. Please try again later. 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=00000000-0000-4000-8000-0000000000a1&status=completed&bulk_list_id=123e4567-e89b-12d3-a456-426614174000' \ --header 'X-API-KEY: ' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.