> ## 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 > Get headline call metrics with the change against the previous period, plus call volume over time, filtered by date, agent, version, campaign or channel. # Get Volume Analytics export const RelatedTopics = ({items}) =>
Related topics
{items.map(([title, href]) => {title} )}
; Returns the numbers behind the **Volume** cards and trend chart in [Analytics](/documentation/monitor/analytics). Each card has `count`, `previous` (the period of the same length just before) and `delta_pct`. ## Notes * `sum(by_bucket[].total)` equals `total.count`, and in each bucket `total = completed + failed + cancelled + registered + ongoing + retry`. * `total.campaign_count` and `total.api_count` split the current total by where calls came from. A callback counts toward its parent call's campaign. * `callback_count` always reports callback calls, whatever `include_callback` is set to. It overlaps `total` only when `include_callback=true`. * `connection_rate.campaign_time_exhausted` and `connection_rate.retry_exhausted` count calls stopped by the campaign's end time or retry limit. * `aht_seconds.duration_distribution` counts completed calls in four buckets: under 10 seconds, 10 to 30, 30 to 60, and 60 or more. * `unique_numbers_used` is the phone numbers your workspace owns, so it ignores the date range and filters. * With a call `channel` filter, chats are left out and `chat_total.count` is `0`. ## Errors * `400`: a filter is invalid, such as an unknown `channel`, a malformed ID, or `sub_workspace_id` sent from a workspace that isn't a primary workspace. * `401`: `X-API-KEY` is missing or invalid. ## OpenAPI ````yaml get /analytics/v4/volume-graph 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: - ApiKeyAuth: [] 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: >- Analytics v4 endpoints for call, agent, cohort and chat performance metrics. - name: termination description: Endpoints for terminating active calls using different methods. - name: knowledgebase description: Endpoints for managing knowledge bases. paths: /analytics/v4/volume-graph: get: tags: - analytics summary: Get Volume Analytics description: >- Returns the headline call metrics (total, connected, failed, connection rate, handle time, minutes and more), each compared with the previous period, plus call volume over time. operationId: getVolumeAnalytics parameters: - name: start_date in: query description: >- Start of the reporting window. Accepts `YYYY-MM-DD` or ISO-8601. Omit both dates for all time. required: false schema: type: string example: '2026-10-01' - name: end_date in: query description: >- End of the reporting window (inclusive). Accepts `YYYY-MM-DD` or ISO-8601. required: false schema: type: string example: '2026-10-15' - name: agent_id in: query description: Filter by one or more agent IDs (comma-separated). required: false schema: type: string example: 00000000-0000-4000-8000-0000000000a1 - name: agent_version_id in: query description: Filter by one or more agent version IDs (comma-separated). required: false schema: type: string example: 00000000-0000-4000-8000-0000000000d1 - name: bulk_list_id in: query description: >- Filter by one or more campaign (bulk list) IDs (comma-separated). Callback calls inherit the campaign of their parent call. required: false schema: type: string example: 00000000-0000-4000-8000-0000000000c1 - name: voicemail in: query description: >- `true` returns only voicemail calls, `false` excludes them. Omit to include all calls. required: false schema: type: boolean example: false - name: channel in: query description: >- Filter by call channel (comma-separated): `inbound`, `outbound`, `webcall`. Unknown values return `400`. required: false schema: type: string example: outbound - name: include_callback in: query description: >- Include callback-feature calls (`call_category = CALLBACK`) in the metrics. Defaults to `false`. required: false schema: type: boolean default: false example: false - name: sub_workspace_id in: query description: >- Primary workspaces only: limit the combined analytics to these Ringg Spaces. Repeat the parameter for multiple IDs. The primary workspace's own ID is accepted; any other workspace sending this parameter gets `400`. required: false schema: type: array items: type: string format: uuid example: - 00000000-0000-4000-8000-000000000101 style: form explode: true - name: tz in: query description: >- IANA timezone used to bucket the time series (for example `Asia/Kolkata`). Bucket labels are returned in this timezone. Omitted or invalid values fall back to UTC. required: false schema: type: string example: Asia/Kolkata responses: '200': description: Volume analytics retrieved successfully. content: application/json: schema: type: object properties: volume: type: object properties: total: type: object description: All calls in scope, across every status. properties: count: type: number description: Value for the selected window. previous: type: number description: >- Value for the equal-length window immediately before. delta_pct: type: number description: >- Relative change from `previous`, in percent. `null` when `previous` is 0. nullable: true campaign_count: type: integer description: >- Calls that came from a campaign (current window only). api_count: type: integer description: >- Calls placed through the API (current window only). callback_count: type: object description: >- Callback-feature calls in scope. Always reported, whatever `include_callback` is set to. properties: count: type: number description: Value for the selected window. previous: type: number description: >- Value for the equal-length window immediately before. delta_pct: type: number description: >- Relative change from `previous`, in percent. `null` when `previous` is 0. nullable: true registered: type: object description: Calls queued but not yet dialed. properties: count: type: number description: Value for the selected window. previous: type: number description: >- Value for the equal-length window immediately before. delta_pct: type: number description: >- Relative change from `previous`, in percent. `null` when `previous` is 0. nullable: true ongoing: type: object description: Calls in progress. properties: count: type: number description: Value for the selected window. previous: type: number description: >- Value for the equal-length window immediately before. delta_pct: type: number description: >- Relative change from `previous`, in percent. `null` when `previous` is 0. nullable: true retry: type: object description: Calls waiting for a retry. properties: count: type: number description: Value for the selected window. previous: type: number description: >- Value for the equal-length window immediately before. delta_pct: type: number description: >- Relative change from `previous`, in percent. `null` when `previous` is 0. nullable: true not_dialed: type: object description: Calls that were never dialed. properties: count: type: number description: Value for the selected window. previous: type: number description: >- Value for the equal-length window immediately before. delta_pct: type: number description: >- Relative change from `previous`, in percent. `null` when `previous` is 0. nullable: true connected: type: object description: Completed calls. properties: count: type: number description: Value for the selected window. previous: type: number description: >- Value for the equal-length window immediately before. delta_pct: type: number description: >- Relative change from `previous`, in percent. `null` when `previous` is 0. nullable: true failed: type: object description: Failed or errored calls. properties: count: type: number description: Value for the selected window. previous: type: number description: >- Value for the equal-length window immediately before. delta_pct: type: number description: >- Relative change from `previous`, in percent. `null` when `previous` is 0. nullable: true cancelled: type: object description: Cancelled calls. properties: count: type: number description: Value for the selected window. previous: type: number description: >- Value for the equal-length window immediately before. delta_pct: type: number description: >- Relative change from `previous`, in percent. `null` when `previous` is 0. nullable: true connection_rate: type: object description: '`connected / total`, as a 0-1 ratio.' properties: count: type: number description: Value for the selected window. previous: type: number description: >- Value for the equal-length window immediately before. delta_pct: type: number description: >- Relative change from `previous`, in percent. `null` when `previous` is 0. nullable: true campaign_time_exhausted: type: integer description: Calls stopped because the campaign window ended. retry_exhausted: type: integer description: Calls that hit the retry limit. voicemail: type: object description: Calls that reached voicemail. properties: count: type: number description: Value for the selected window. previous: type: number description: >- Value for the equal-length window immediately before. delta_pct: type: number description: >- Relative change from `previous`, in percent. `null` when `previous` is 0. nullable: true aht_seconds: type: object description: Average handle time of completed calls, in seconds. properties: count: type: number description: Value for the selected window. previous: type: number description: >- Value for the equal-length window immediately before. delta_pct: type: number description: >- Relative change from `previous`, in percent. `null` when `previous` is 0. nullable: true duration_distribution: type: object description: Completed calls by duration (current window only). properties: 0_10: type: integer description: Completed calls shorter than 10 seconds. 10_30: type: integer description: Completed calls of 10-30 seconds. 30_60: type: integer description: Completed calls of 30-60 seconds. 60_plus: type: integer description: Completed calls of 60 seconds or more. total_minutes: type: object description: Total talk minutes. properties: count: type: number description: Value for the selected window. previous: type: number description: >- Value for the equal-length window immediately before. delta_pct: type: number description: >- Relative change from `previous`, in percent. `null` when `previous` is 0. nullable: true unique_numbers_used: type: object description: >- Phone numbers your workspace owns. It doesn't change with the date range or filters, so `previous` equals `count`. properties: count: type: number description: Value for the selected window. previous: type: number description: >- Value for the equal-length window immediately before. delta_pct: type: number description: >- Relative change from `previous`, in percent. `null` when `previous` is 0. nullable: true chat_total: type: object description: >- Chat sessions. `0` when a call `channel` filter is set. properties: count: type: number description: Value for the selected window. previous: type: number description: >- Value for the equal-length window immediately before. delta_pct: type: number description: >- Relative change from `previous`, in percent. `null` when `previous` is 0. nullable: true total_interactions: type: object description: Calls plus chat sessions. properties: count: type: number description: Value for the selected window. previous: type: number description: >- Value for the equal-length window immediately before. delta_pct: type: number description: >- Relative change from `previous`, in percent. `null` when `previous` is 0. nullable: true by_bucket: type: array description: >- Call volume over time. `sum(by_bucket[].total)` equals `total.count`. items: type: object properties: bucket: type: string description: >- Time bucket label. Granularity is picked from the date range: hour `YYYY-MM-DD HH:00:00`, day `YYYY-MM-DD`, week (Monday) or month (first day). total: type: integer description: All calls in the bucket. completed: type: integer description: Completed calls. failed: type: integer description: Failed or errored calls. cancelled: type: integer description: Cancelled calls. registered: type: integer description: Queued calls. ongoing: type: integer description: In-progress calls. retry: type: integer description: Calls waiting for a retry. example: volume: total: count: 203 previous: 239 delta_pct: -15.06 campaign_count: 51 api_count: 152 callback_count: count: 12 previous: 10 delta_pct: 20 registered: count: 2 previous: 0 delta_pct: null ongoing: count: 1 previous: 0 delta_pct: null retry: count: 0 previous: 0 delta_pct: null not_dialed: count: 3 previous: 5 delta_pct: -40 connected: count: 179 previous: 198 delta_pct: -9.6 failed: count: 19 previous: 39 delta_pct: -51.28 cancelled: count: 2 previous: 2 delta_pct: 0 connection_rate: count: 0.8818 previous: 0.8285 delta_pct: 6.43 campaign_time_exhausted: 4 retry_exhausted: 12 voicemail: count: 6 previous: 9 delta_pct: -33.33 aht_seconds: count: 40.7 previous: 41.2 delta_pct: -1.21 duration_distribution: 0_10: 20 10_30: 40 30_60: 80 60_plus: 39 total_minutes: count: 121.4 previous: 140.9 delta_pct: -13.84 unique_numbers_used: count: 8 previous: 8 delta_pct: 0 chat_total: count: 2 previous: 1 delta_pct: 100 total_interactions: count: 205 previous: 240 delta_pct: -14.58 by_bucket: - bucket: '2026-10-14' total: 40 completed: 33 failed: 5 cancelled: 0 registered: 1 ongoing: 1 retry: 0 '400': description: >- Bad Request - invalid filter value (for example an unknown `channel` or malformed ID). content: application/json: example: message: 'invalid channel(s): sms' '401': description: Unauthorized - Invalid or missing authentication. '500': description: Internal Server Error. content: application/json: example: message: Failed to fetch volume graph! components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.