#Calls Analytics

Retrieve call records, transcripts, sentiment analysis, and export call data. Protected endpoints accept either X-API-Key or Authorization: Bearer <jwt> authentication and return data scoped to the resolved AuthContext.

Production API: https://api.aidial.ai

This page omits environment-specific host names, internal topology, and deployment details.

#Authentication And Scoping

Authentication is resolved in this order:

1. X-API-Key
2. Authorization: Bearer <jwt>

If both headers are present, the API key is used. Missing or invalid authentication returns 401 Unauthorized.

Bearer authentication is for AiDial Portal sessions. Bearer validation requires ZITADEL_ISSUER, ZITADEL_AUDIENCE, and ZITADEL_JWKS_URL; these settings are required and have no fallback defaults. Bearer tenant assignment is resolved from portal_users and portal_user_client_assignments.

Both authentication modes resolve to client_id, data_env, scope, and principal metadata. Analytics and call data are routed by the strict (client_id, data_env) mapping in the tenant routing map; metadata, authentication, portal assignment, project configuration, export state, and audit records use the local API metadata store on the API host. A missing tenant route is server misconfiguration and returns 500 Internal Server Error. If the routed data host, tunnel, or database is unavailable, the API returns 503 Service Unavailable.

PII-sensitive fields respect the client-level PII flags in aidial_clients. Phone and transcript decryption goes through server-side decryption pathways when plaintext access is permitted. If PII permissions are missing, permission lookup fails, or decryption fails, the API fails closed by redacting or omitting PII. Raw encrypted database fields such as *_encrypted, ciphertext, wrapped keys, and nonces are not response fields.

#GET /v1/calls/summary

Returns aggregate call statistics for your organisation.

Authentication: Required (X-API-Key or Authorization: Bearer <jwt>)

#Parameters

#Response

Display guidance: prefer the local-currency fields only when currency is non-null; otherwise display the USD fields explicitly labelled as USD rather than guessing a currency. The USD fields remain unchanged for all callers.

Disconnection reason guidance:

• disconnection_reason_distribution is a normalized Aidial API taxonomy, not raw LiveKit, SIP, telephony, or provider metadata.
• Counts use the same resolved client_id, data_env, date, project_id, and solution_id scope as the rest of the summary response.
• The fallback order is transfer evidence, missed, failed, explicit caller hangup, explicit agent/system end, then unknown.
• Transfer evidence comes from persisted ai_calls.call_metadata.transfer.attempts named targets (target, destination_key, or destination_name) in keyed-object or array-shaped attempt metadata, or transfer resolution metadata. Direct-call and in-progress transfer markers are ignored.
• call_status = completed by itself is not enough evidence for caller_hangup or agent_or_system_end; missing, legacy, blank, or unrecognized metadata counts as unknown.
• Empty scoped results return all six buckets as 0; non-empty distributions sum to total_calls.
• A hidden legacy partner passthrough is also served at /v1/calls/summary by the partner call-control router (excluded from the OpenAPI schema and registered ahead of the public summary route). It delegates to the same handler and returns the same normalized response model after the caller's target-client authority is resolved.

#Example

Request:

curl -X GET "https://api.aidial.ai/v1/calls/summary?start_date=2026-03-01&end_date=2026-03-15" \
  -H "X-API-Key: sk_live_YOUR_API_KEY_HERE"

Response (200 OK):

{
  "total_calls": 142,
  "completed_calls": 120,
  "missed_calls": 15,
  "failed_calls": 7,
  "total_duration_seconds": 28400,
  "avg_duration_seconds": 200,
  "total_cost_usd": 42.60,
  "avg_cost_usd": 0.30,
  "currency": "AUD",
  "total_cost_local": 64.39,
  "avg_cost_local": 0.45,
  "human_escalation_count": 8,
  "sentiment_distribution": {"positive": 85, "neutral": 42, "negative": 15},
  "caller_sentiment_distribution": {"positive": 85, "neutral": 42, "negative": 15},
  "disconnection_reason_distribution": {
    "caller_hangup": 82,
    "agent_or_system_end": 25,
    "transferred": 13,
    "missed": 15,
    "failed": 7,
    "unknown": 0
  },
  "avg_ai_response_seconds": 1.2
}

#GET /v1/calls/outcomes

Returns the Rev 6 dashboard conversation outcome aggregate for one scoped project and date range.

Authentication: Required (X-API-Key or Authorization: Bearer <jwt>)

#Parameters

#Source And Empty-State Semantics

• Category ids and labels come only from the selected project's API-managed dashboard outcome_enum.
• Calls are counted from routed tenant call records scoped by the resolved target client_id, authenticated data_env, project_id, and date range.
• Primary outcome derivation uses persisted evidence only: exact in-taxonomy values from booking_result, transfer_result, or call_resolution_status, then capability/status rollups only when the project taxonomy explicitly declares a known outcome family label key.
• Categories not present in the project taxonomy are not returned, even when matching call evidence exists.
• Missing taxonomy or unsupported data returns categories: [], classified_count: 0, and unclassified_count equal to the scoped total.
• The API does not infer families from English taxonomy ids or labels. Additional SQL evidence keys require a documented project taxonomy extension contract before they are added.
• The response never includes caller PII, transcript text, summaries, raw analysis_data, prompt text, encrypted fields, recordings, API keys, bearer tokens, or secret-backend references.

#Empty / Unknown Rendering Guidance

• When total_conversations == 0, render the outcomes panel as an empty range state. Do not render a donut wedge.
• When total_conversations > 0 && classified_count == 0, render an unknown taxonomy/evidence state. The donut may show a single portal-owned "Unclassified" wedge using a portal i18n key such as outcomes.unclassified.title.
• When total_conversations > 0 && unclassified_count > 0, include an "Unclassified" wedge or equally visible coverage indicator so the classified donut does not imply full coverage. The unclassified label is portal-owned i18n, not API-provided taxonomy text.
• When categories[].capability is present, clients may surface a follow-up affordance tied to that bucket. Absence of capability must not be treated as "capability disabled"; it only means the taxonomy entry was not mapped to an enabled booking or transfer capability hint.
• source and taxonomy_revision are contract identifiers for developers and diagnostics. Do not show them directly as customer-facing copy; map them to localized labels or hide them.

#Response

#Example

Request:

curl -X GET "https://api.aidial.ai/v1/calls/outcomes?project_id=proj_example_001&start_date=2026-03-01&end_date=2026-03-15" \
  -H "Authorization: Bearer PORTAL_SESSION_JWT"

Response (200 OK):

{
  "project_id": "proj_example_001",
  "start_date": "2026-03-01",
  "end_date": "2026-03-15",
  "total_conversations": 142,
  "classified_count": 130,
  "unclassified_count": 12,
  "taxonomy_revision": "published:7:safe",
  "source": "project_taxonomy_derived_call_evidence",
  "categories": [
    {
      "id": "booked_appointment",
      "label": "Booked appointment",
      "label_key": "outcomes.booking.title",
      "count": 38,
      "percentage": 26.76,
      "capability": "booking"
    }
  ]
}

#GET /v1/calls/dashboard/privacy-aggregates

Returns privacy-safe Rev 6 dashboard data for the recent calls list and caller mix card.

Authentication: Required (X-API-Key or Authorization: Bearer <jwt>)

#Parameters

#Source And Privacy Semantics

• Recent-call outcomes use the same project_taxonomy_derived_call_evidence classifier as GET /v1/calls/outcomes.
• Recent-call rows are intentionally small: call id, start time, duration, normalized sentiment, safe outcome label, and entitlement-driven detail availability only.
• Caller mix is an aggregate only. The API may use server-side caller identity evidence to count unique, new, and returning callers over a 30-day lookback, but grouping uses a tenant-scoped HMAC-SHA-256 key inside the routed database and no identity value or hash is returned.
• caller_mix.status = available with reason_code = ready includes aggregate counts, percentages, total calls, and average calls per caller.
• caller_mix.status = available with reason_code = no_calls returns zero metrics for an empty range when matching is supported.
• caller_mix.status = unavailable with reason_code = unsupported means the project has no supported privacy-safe caller mix capability.
• caller_mix.status = unavailable with reason_code = identity_unavailable means calls exist but safe matching evidence is unavailable or only partially covers the selected calls.
• caller_mix.status = unavailable with reason_code = below_k means identity evidence exists but the unique caller population, new caller bucket, or returning caller bucket is below the minimum caller-mix threshold of 5; identity-derived metrics are omitted.
• Unclassified recent-call outcomes carry label_key = "outcomes.unclassified.title" so the portal can localize the safe fallback label.
• detail_available is true only for the owning tenant's client_admin sessions and assigned partner_admin sessions; read-only, internal, API-key, or partial-scope callers receive false.
• The API emits dashboard_privacy_aggregates_read audit events for successful reads and non-enumerating project-scope denials. Audit metadata records actor client, target client, project, and reason code, and excludes caller identity, HMAC output, and salts.
• The response never includes caller names, full or masked phone numbers, CRM patient labels, caller ids, stable identity hashes, transcript text, summaries, recordings, raw analysis_data, encrypted fields, API keys, bearer tokens, secrets, or secret-backend references.

#Response

#Example

Request:

curl -X GET "https://api.aidial.ai/v1/calls/dashboard/privacy-aggregates?project_id=proj_example_001&start_date=2026-03-01&end_date=2026-03-15&recent_limit=5" \
  -H "Authorization: Bearer PORTAL_SESSION_JWT"

Response (200 OK):

{
  "project_id": "proj_example_001",
  "start_date": "2026-03-01",
  "end_date": "2026-03-15",
  "source": "project_taxonomy_derived_call_evidence",
  "recent_calls": [
    {
      "call_id": "LK-room-001",
      "started_at_utc": "2026-03-15T02:10:00Z",
      "duration_seconds": 184,
      "sentiment": "positive",
      "outcome": {
        "id": "booked_appointment",
        "label": "Booked appointment",
        "label_key": "outcomes.booking.title",
        "state": "classified"
      },
      "detail_available": true
    }
  ],
  "caller_mix": {
    "status": "available",
    "reason_code": "ready",
    "lookback_days": 30,
    "metrics": {
      "total_calls": 70,
      "unique_callers": 52,
      "new_callers": 36,
      "returning_callers": 16,
      "new_callers_percent": 69.23,
      "returning_callers_percent": 30.77,
      "avg_calls_per_caller": 1.35
    }
  }
}

#GET /v1/calls/list

Returns a paginated list of call records with optional filtering and sorting.

Authentication: Required (X-API-Key or Authorization: Bearer <jwt>)

#Parameters

#Response

Pagination note: Results use offset-based pagination. If new records are inserted between page requests, results may shift. For consistent snapshots, use narrow date ranges.

#Example

Request:

curl -X GET "https://api.aidial.ai/v1/calls/list?project_id=proj_example_001&page=1&page_size=2&start_date=2026-03-01&sort_by=started_at_desc" \
  -H "X-API-Key: sk_live_YOUR_API_KEY_HERE"

Response (200 OK):

{
  "calls": [
    {
      "call_id": "call_00000000-0000-4000-a000-000000000001",
      "client_id": "client_example_001",
      "project_id": "proj_example_001",
      "solution_id": "sol_example_001",
      "started_at_utc": "2026-03-15T09:30:00Z",
      "ended_at_utc": "2026-03-15T09:35:22Z",
      "duration_seconds": 322,
      "call_status": "completed",
      "call_direction": "inbound",
      "channel": "phone",
      "from_number": "+61 400 000 001",
      "to_number": "+61 2 0000 0001",
      "summary": "Caller requested an appointment booking for next Tuesday.",
      "summary_status": "ok",
      "sentiment_label_extension": null,
      "transfer_destination": {
        "label": "Front desk",
        "destination_type": "external_number",
        "revision_id": "trv_5f8c20a47b9b41acb2"
      },
      "primary_outcome": {
        "id": "booked_appointment",
        "label": "Booked appointment",
        "label_key": "outcomes.booking.title",
        "state": "classified"
      },
      "call_resolution_status": "resolved",
      "booking_result": "booked",
      "transfer_result": "unavailable",
      "follow_up_status": "sent",
      "sms_status": "unavailable",
      "email_status": "sent",
      "sentiment_overall": "positive",
      "caller_sentiment": "positive",
      "message_count": 12,
      "human_escalation_needed": false,
      "cost_usd": 0.48,
      "llm_token_used": 1250,
      "stt_minutes_processed": 5.37,
      "tts_characters_synthesized": 3200,
      "llm_provider": "openai",
      "llm_model": "gpt-4o",
      "transcript_messages": null
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 2,
    "total_records": 142,
    "total_pages": 71
  },
  "scope": {
    "empty_state_reason": null
  }
}

#GET /v1/calls/timeline

Returns time-series call metrics for charting.

Authentication: Required (X-API-Key or Authorization: Bearer <jwt>)

#Parameters

#Response

#Example

Request:

curl -X GET "https://api.aidial.ai/v1/calls/timeline?start_date=2026-03-10&end_date=2026-03-15&interval=day" \
  -H "X-API-Key: sk_live_YOUR_API_KEY_HERE"

Response (200 OK):

{
  "timeline": [
    {
      "period": "2026-03-10T00:00:00Z",
      "total_calls": 18,
      "completed_calls": 15,
      "missed_calls": 2,
      "failed_calls": 1,
      "total_duration_seconds": 3600,
      "avg_duration_seconds": 200,
      "total_cost_usd": 5.40,
      "human_escalation_count": 1
    }
  ]
}

#GET /v1/calls/sentiment

Returns sentiment distribution across calls. Both start_date and end_date are required.

Authentication: Required (X-API-Key or Authorization: Bearer <jwt>)

#Parameters

Date boundary semantics match /v1/calls/summary:

• A YYYY-MM-DD end_date is inclusive of that whole UTC day.
• An ISO 8601 datetime end_date is the exclusive UTC upper bound and is not expanded by an extra day.
• A reversed range (start after end) returns 400; mixed date/datetime ranges are compared safely on UTC boundaries.
• For an identical window and scope, the distribution total_calls aligns with /v1/calls/summary total_calls.

#Response

#Example

Request:

curl -X GET "https://api.aidial.ai/v1/calls/sentiment?start_date=2026-03-01&end_date=2026-03-15" \
  -H "X-API-Key: sk_live_YOUR_API_KEY_HERE"

Response (200 OK):

{
  "overall": {"positive": 85, "neutral": 42, "negative": 15, "analyzed": 142},
  "caller": {"positive": 90, "neutral": 38, "negative": 14, "analyzed": 142},
  "agent": {"positive": 100, "neutral": 35, "negative": 7, "analyzed": 142},
  "total_calls": 142,
  "start_date": "2026-03-01",
  "end_date": "2026-03-15"
}

#GET /v1/calls/sentiment/timeline

Returns sentiment trend over time. Both start_date and end_date are required. The response includes dense time buckets for the requested interval; buckets with no matching calls return zero counts and zero percentages.

Authentication: Required (X-API-Key or Authorization: Bearer <jwt>)

#Parameters

Date boundary semantics match /v1/calls/summary:

• A YYYY-MM-DD end_date is inclusive of that whole UTC day.
• An ISO 8601 datetime end_date is the exclusive UTC upper bound and is not expanded by an extra day. The dense bucket range still spans the requested start/end calendar window.
• A reversed range (start after end) returns 400; mixed date/datetime ranges are compared safely on UTC boundaries.

#Response

#Example

Request:

curl -X GET "https://api.aidial.ai/v1/calls/sentiment/timeline?start_date=2026-03-10&end_date=2026-03-15&interval=day" \
  -H "X-API-Key: sk_live_YOUR_API_KEY_HERE"

Response (200 OK):

{
  "timeline": [
    {
      "period": "2026-03-10T00:00:00Z",
      "total_calls": 18,
      "positive_count": 12,
      "neutral_count": 5,
      "negative_count": 1,
      "positive_percent": 66.7,
      "neutral_percent": 27.8,
      "negative_percent": 5.6
    }
  ],
  "start_date": "2026-03-10",
  "end_date": "2026-03-15",
  "interval": "day"
}

#GET /v1/calls/provider-performance

Returns scoped provider and latency analytics for dashboard comparison views.

Authentication: Required (X-API-Key or Authorization: Bearer <jwt>) Scopes: client_staff, client_admin, client_manager, partner_admin, partner_user, aidial_admin, aidial_operator, read-only, or full-access

#Parameters

#Response

The endpoint reads only allowlisted call timing and provider fields from routed tenant call records. It does not return transcripts, summaries, phone numbers, recording URLs, encrypted fields, API keys, bearer tokens, or secret-backend references.

Error semantics:

• 400 INVALID_DATE_RANGE, DATE_RANGE_TOO_LARGE, INVALID_TIMEZONE, or INVALID_FILTER for invalid query input.
• 404 NOT_AUTHORIZED for out-of-scope clients, projects, roles, categories, or provider filters.
• 503 UPSTREAM_DATA_UNAVAILABLE when routed analytics data cannot be read.

#Example

Request:

curl -X GET "https://api.aidial.ai/v1/calls/provider-performance?start_date=2026-03-01T00:00:00Z&end_date=2026-03-15T00:00:00Z&timezone=Australia%2FBrisbane&project_id=proj_example_001&category=llm" \
  -H "Authorization: Bearer PORTAL_SESSION_JWT"

#GET /v1/calls/{call_id}

Returns scoped detail for a single call. Transcript and phone visibility depend on the authenticated role and client PII configuration.

Authentication: Required (X-API-Key or Authorization: Bearer <jwt>) Access: Scoped to the resolved tenant and project. Out-of-scope calls return non-enumerating 404

#Parameters

#Response

The response model does not include recording URLs, partner tags, external references, or raw encrypted transcript artifacts.

#Example

Request:

curl -X GET "https://api.aidial.ai/v1/calls/call_00000000-0000-4000-a000-000000000001" \
  -H "X-API-Key: sk_live_YOUR_API_KEY_HERE"

Response (200 OK):

{
  "call_id": "call_00000000-0000-4000-a000-000000000001",
  "client_id": "client_example_001",
  "project_id": "proj_example_001",
  "solution_id": "sol_example_001",
  "compliance_required": true,
  "compliance_jurisdiction": "AU",
  "started_at_utc": "2026-03-15T09:30:00Z",
  "ended_at_utc": "2026-03-15T09:35:22Z",
  "duration_seconds": 322,
  "call_status": "completed",
  "call_direction": "inbound",
  "channel": "phone",
  "from_number": "+61 400 000 001",
  "to_number": "+61 2 0000 0001",
  "summary": "Caller requested an appointment booking for next Tuesday.",
  "summary_status": "ok",
  "sentiment_label_extension": null,
  "transfer_destination": null,
  "primary_outcome": {
    "id": "booked_appointment",
    "label": "Booked appointment",
    "label_key": "outcomes.booking.title",
    "state": "classified"
  },
  "sentiment_overall": "positive",
  "caller_sentiment": "positive",
  "agent_sentiment": "neutral",
  "message_count": 2,
  "transcript": [
    {"speaker": "agent", "timestamp": 0.2, "text": "Good morning, how can I help you today?", "sentiment": null},
    {"speaker": "caller", "timestamp": 3.1, "text": "I would like to book an appointment.", "sentiment": "positive"}
  ],
  "call_resolution_status": "resolved",
  "ai_first_response_seconds": 1.2,
  "human_escalation_needed": false,
  "human_intervention_count": 0,
  "cost_usd": 0.48,
  "cost_local": 0.73,
  "cost_local_currency": "AUD",
  "cost_breakdown": null,
  "llm_token_used": 1250,
  "stt_minutes_processed": 5.37,
  "tts_characters_synthesized": 3200,
  "cloud_provider": "aws",
  "cloud_region": "ap-southeast-2",
  "llm_provider": "openai",
  "llm_model": "gpt-4o",
  "stt_provider": "deepgram",
  "tts_provider": "elevenlabs",
  "tts_voice": "voice_example",
  "telephony_provider": "twilio",
  "telephony_call_id": "CA00000000000000000000000000000001",
  "livekit_room_name": "room_00000000-0000-4000-a000-000000000001",
  "agent_identity": "agent_example",
  "caller_identity": null,
  "latency_metrics": null,
  "analysis_data": null
}

#GET /v1/calls/{call_id}/inline-preview

Returns the closed, redacted preview used by Portal call-list row expansion.

Authentication: Required (X-API-Key or Authorization: Bearer <jwt>)

#Parameters

#Response

The inline preview uses the pre-redacted transcript path and does not decrypt original transcript ciphertext. Partner bearer sessions hide transcript text and return transcript_state: "redacted_hidden". Missing or out-of-scope calls return 404; routed data-host failures return 503.

#Transcript Quality

Transcript quality endpoints expose redacted transcript review state and allow eligible Portal users to record corrections, annotations, and disputes.

Authentication: Required (X-API-Key or Authorization: Bearer <jwt>)

#Endpoints

#Roles

Snapshot reads are available to client_admin, client_manager, client_staff, and API-key full-access. Partner roles, internal roles, and API-key read-only receive non-enumerating 404 responses for transcript-quality reads.

Mutations require bearer Portal authentication with a portal user principal. Corrections and disputes are allowed for client_admin and client_manager. Annotations are allowed for client_admin, client_manager, and client_staff.

#Snapshot Response

#Mutation Bodies

User-entered quality text is normalized before persistence. Phone numbers, email addresses, card-like numbers, and identifier-like values are replaced with safe placeholders; secret-like content is rejected. Rejected or unchanged quality text returns 422 QUALITY_TEXT_REJECTED. Invalid request bodies return 400; denied mutations return 403 for read-entitled callers without mutation rights and non-enumerating 404 for callers without transcript-content access; missing or out-of-scope calls return 404; workflow failures return 503.

#GET /v1/calls/{call_id}/transcript-download

Downloads the redacted transcript for a call.

Authentication: Required (X-API-Key or Authorization: Bearer <jwt>) Scopes: client_admin, client_manager, client_staff, or partner_admin

Data handling: Transcripts may contain personal information subject to the Privacy Act 1988 (Cth). All transcript access is audit-logged. Partners should refer to their AiDial partner agreement for data handling obligations. Transcripts are redacted by default based on your client PII configuration. Secondary-use policy does not gate this direct redacted transcript access path; it continues to apply to reuse/export, webhook delivery, reporting, and model-training decisions.

#Parameters

#Response

Returns the transcript as a streamed text attachment (Content-Type: text/plain; charset=utf-8). The attachment filename uses AiDial-Transcript_<project-display-or-id>_<YYYY-MM-DD>_<call-id-suffix>.txt, where <call-id-suffix> is the last 12 characters of the sanitised call id and the date segment is evaluated in the project timezone when available. The text starts with readable call metadata headers (Business, Call date, Duration, Direction, From, To) followed by role-prefixed transcript lines. Project display name and timezone are loaded through tenant-scoped project metadata when they are not present on the routed call row; unavailable metadata falls back to project id and UTC. When include_quality_history=true, correction, annotation, and dispute history is appended in separately labelled sections. Unsupported formats return 400 EXPORT_UNSUPPORTED_FORMAT. If the call is out of scope, unavailable, or the caller lacks transcript access, the endpoint returns 404 Not Found. Download throttling returns 429 with code DOWNLOAD_THROTTLED; generation failures return 503 DOWNLOAD_FAILED.

#Example

Request:

curl -X GET "https://api.aidial.ai/v1/calls/call_00000000-0000-4000-a000-000000000001/transcript-download" \
  -H "X-API-Key: sk_live_YOUR_API_KEY_HERE" \
  -o transcript.txt

#GET /v1/calls/{call_id}/transcript/pdf

Downloads the redacted transcript for a call as a PDF attachment.

Authentication: Required (X-API-Key or Authorization: Bearer <jwt>) Scopes: client_admin, client_manager, client_staff, or partner_admin

Data handling: The PDF is generated from the same redacted transcript path as TXT download. Transcript access is audit-logged. Secondary-use policy does not gate this direct redacted transcript access path; it continues to apply to reuse/export, webhook delivery, reporting, and model-training decisions.

#Parameters

#Response

Returns the transcript as a streamed PDF attachment (Content-Type: application/pdf). The attachment filename uses AiDial-Transcript_<project-display-or-id>_<YYYY-MM-DD>_<call-id-suffix>.pdf, where <call-id-suffix> is the last 12 characters of the sanitised call id and the date segment is evaluated in the project timezone when available, and the PDF header uses the same tenant-scoped project display name, timezone, and redacted call metadata as the TXT export. Per-message labels use elapsed MM:SS offsets when offset or timestamp evidence is available. Transcripts over the 500 KB raw transcript size guard return 413 with code DOWNLOAD_PDF_TOO_LARGE; use TXT download for oversized transcripts. Download throttling returns 429 with code DOWNLOAD_THROTTLED.

#Example

Request:

curl -X GET "https://api.aidial.ai/v1/calls/call_00000000-0000-4000-a000-000000000001/transcript/pdf" \
  -H "X-API-Key: sk_live_YOUR_API_KEY_HERE" \
  -o transcript.pdf

#POST /v1/calls/export

Exports filtered call data as a CSV file.

Authentication: Required (X-API-Key or Authorization: Bearer <jwt>) Scopes (metadata export — sub-surface S-006-METADATA): client_admin, client_manager, client_staff, or partner_admin Scopes (sensitive opt-ins — sub-surfaces S-006-CALLER_INFO, S-006-TRANSCRIPT, S-006-AUDIO_LINKS): client_admin only (S19). Audio-link opt-in requests additionally require project audio retention enabled, but the current CSV writer does not emit a signed audio-link column.

Export behaviour: When rows match, this endpoint returns a streamed CSV file directly in the response body (Content-Type: text/csv; charset=utf-8). It is not an asynchronous job. Large date ranges may result in longer response times. Set appropriate client-side timeouts (recommended minimum: 300 seconds for full-range exports).

#Request Body

#Response

When rows match, returns a CSV attachment with these columns:

CSV values that could be interpreted as spreadsheet formulas are neutralised before streaming.

Sensitive export audit metadata records selected options separately from honoured options. include_audio_links=true is retained in selected options after it passes role and retention checks, but audio_links is deliberately excluded from honoured options until signed-link generation is implemented.

If no rows match, the endpoint returns 200 OK with JSON:

{
  "code": "EXPORT_EMPTY",
  "message": "No matching calls found.",
  "messageKey": "calls.export.messages.empty"
}

Synchronous exports are capped at 10,000 matching rows and guarded by a 30 second wall-time limit. Row counts over the hard cap return 413 EXPORT_TOO_LARGE before the cursor opens. If the wall-time guard trips during streaming, the export stops and the audit row records EXPORT_TOO_LARGE with failure_reason: "wall_time_exceeded". The legacy EXPORT_OVER_CAP (400) code remains for the browser-claimed advisory count cap.

S19 error semantics:

• 422 — one or more required typed booleans are missing or are not JSON booleans. This validation happens before router role, capability, count, or audit handling.
• 400 EXPORT_PROJECT_REQUIRED — project_id was omitted or blank.
• 400 EXPORT_UNSUPPORTED_FORMAT — unsupported export format, when the request reaches the router. The current request model accepts only csv, so most non-CSV values fail request validation before this branch.
• 404 EXPORT_DENIED — the caller's base role cannot use the export surface, or the selected project is out of scope.
• 403 EXPORT_DENIED — sensitive opt-in requested by a non-client_admin role; the request is rejected before any count, cursor, decrypt, or signed-link generation runs.
• 400 EXPORT_UNAVAILABLE — include_audio_links=true against a project whose audio retention is disabled or cannot be confirmed.
• 413 EXPORT_TOO_LARGE — synchronous row cap exceeded before streaming starts. Wall-time overruns are recorded in export audit metadata while streaming is stopped.

S19 example body (metadata-only):

{
  "project_id": "proj_example_001",
  "start_date": "2026-03-01",
  "end_date": "2026-03-15",
  "format": "csv",
  "include_caller_info": false,
  "include_transcript_text": false,
  "include_audio_links": false
}

#Example

Request:

curl -X POST "https://api.aidial.ai/v1/calls/export" \
  -H "X-API-Key: sk_live_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_example_001",
    "start_date": "2026-03-01",
    "end_date": "2026-03-15",
    "format": "csv",
    "include_caller_info": false,
    "include_transcript_text": false,
    "include_audio_links": false
  }' \
  -o calls_export.csv

#Rate Limiting

Only one export can run at a time for the same user and tenant. Concurrent exports return 409 with code EXPORT_IN_PROGRESS. If rate-limited, the export endpoint returns:

Response (429 Too Many Requests):

{
  "error": "rate_limited",
  "code": "EXPORT_THROTTLED",
  "message": "Export throttled. Please wait and try again.",
  "messageKey": "calls.export.messages.throttled",
  "retry_after_seconds": 60
}

#POST /v1/calls/{call_id}/audit-pii-access

Logs that PII for a call was accessed. This endpoint records the access against the routed call record and emits a portal audit event.

Authentication: Required (X-API-Key or Authorization: Bearer <jwt>)

#Parameters

#Request Body

#Response

#Example

Request:

curl -X POST "https://api.aidial.ai/v1/calls/call_00000000-0000-4000-a000-000000000001/audit-pii-access" \
  -H "X-API-Key: sk_live_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"access_type": "view_transcript", "accessed_by": "user@example.com", "access_context": "portal"}'

Response (200 OK):

{
  "status": "success",
  "message": "PII access logged successfully"
}

#Data Scoping

All responses are scoped to your authenticated client_id and data_env. You only see calls belonging to your organisation and routed environment. Accessing calls outside your scope returns 404 Not Found.

#Related Pages

• Authentication — API key and bearer authentication
• Error Responses — error format details
• Rate Limiting — handling 429 responses