Calls & Recordings

The Calls API provides access to voice call sessions, transcripts, and recording metadata. Every AI voice conversation — whether from phone, mobile app, or web widget — is tracked as a call record.

List Calls

cURL

curl "https://apps.aurionai.net/api/v1/calls?limit=10&start_date=2026-03-01T00:00:00Z&end_date=2026-03-31T23:59:59Z" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Python

import requests

response = requests.get(
    "https://apps.aurionai.net/api/v1/calls",
    headers={"X-API-Key": "itsm_sk_live_xxxx"},
    params={
        "limit": 10,
        "start_date": "2026-03-01T00:00:00Z",
        "end_date": "2026-03-31T23:59:59Z",
    },
)
calls = response.json()

TypeScript

const response = await fetch(
  "https://apps.aurionai.net/api/v1/calls?limit=10&start_date=2026-03-01T00:00:00Z&end_date=2026-03-31T23:59:59Z",
  {
    headers: { "X-API-Key": "itsm_sk_live_xxxx" },
  }
);
const calls = await response.json();

Response:

{
  "calls": [
    {
      "id": "9f1c8e3a-7b2d-4c5e-8f90-1a2b3c4d5e6f",
      "twilio_call_sid": "CA1234567890abcdef1234567890abcdef",
      "livekit_room_id": "call-9f1c8e3a",
      "phone_number": "+33612345678",
      "direction": "inbound",
      "status": "completed",
      "start_time": "2026-03-08T10:30:00Z",
      "end_time": "2026-03-08T10:33:05Z",
      "duration_seconds": 185,
      "recording_url": "recordings/production/0b6e2c1d-4f3a-4e8b-9c7d-2a1b3c4d5e6f/2026/03/9f1c8e3a-7b2d-4c5e-8f90-1a2b3c4d5e6f.wav",
      "recording_duration_seconds": 185,
      "recording_size_bytes": 1482240,
      "recording_format": "wav",
      "outcome": "resolved",
      "created_at": "2026-03-08T10:30:00Z",
      "updated_at": "2026-03-08T10:33:05Z"
    }
  ],
  "total": 234,
  "limit": 10,
  "offset": 0
}

Query Parameters:

Parameter	Type	Description
`start_date`	string	Optional ISO-8601 date-time. Returns only calls where `start_time >= start_date`.
`end_date`	string	Optional ISO-8601 date-time. Returns only calls where `start_time <= end_date`.
`limit`	integer	Results per page (default: 20, min: 1, max: 100)
`offset`	integer	Number of results to skip (default: 0)

Results are always ordered by start_time descending. Unknown query parameters are ignored.

Get Call Details

curl "https://apps.aurionai.net/api/v1/calls/9f1c8e3a-7b2d-4c5e-8f90-1a2b3c4d5e6f" \
  -H "X-API-Key: itsm_sk_live_xxxx"

The call_id path parameter is a UUID. A non-UUID value returns 422. An unknown or cross-tenant ID returns 404 {"detail": "Call not found"}.

Response:

{
  "id": "9f1c8e3a-7b2d-4c5e-8f90-1a2b3c4d5e6f",
  "twilio_call_sid": "CA1234567890abcdef1234567890abcdef",
  "livekit_room_id": "call-9f1c8e3a",
  "phone_number": "+33612345678",
  "direction": "inbound",
  "status": "completed",
  "start_time": "2026-03-08T10:30:00Z",
  "end_time": "2026-03-08T10:33:05Z",
  "duration_seconds": 185,
  "recording_url": "recordings/production/0b6e2c1d-4f3a-4e8b-9c7d-2a1b3c4d5e6f/2026/03/9f1c8e3a-7b2d-4c5e-8f90-1a2b3c4d5e6f.wav",
  "recording_duration_seconds": 185,
  "recording_size_bytes": 1482240,
  "recording_format": "wav",
  "outcome": "resolved",
  "created_at": "2026-03-08T10:30:00Z",
  "updated_at": "2026-03-08T10:33:05Z"
}

The detail response is identical to a single item in the list response.

Call Fields:

Field	Type	Description
`id`	string	Call UUID
`twilio_call_sid`	string	Twilio call SID (for PSTN calls)
`livekit_room_id`	string	LiveKit room identifier for the session
`phone_number`	string	Caller identifier as the channel provides it, so not always an E.164 number. Phone calls carry the caller's number as received (it can lack the `+`, or be prefixed `sip_`), or `unknown`; web widget, WebRTC and mobile-app calls carry `unknown`. Any other stored value, such as the caller's email address or display name on calls recorded up to early August 2026, is returned as `unknown`
`direction`	string	Call direction, typically `inbound` or `outbound`
`status`	string	Call status (see below)
`start_time`	string \| null	ISO-8601 call start time
`end_time`	string \| null	ISO-8601 call end time
`duration_seconds`	integer \| null	Call duration in seconds
`recording_url`	string \| null	Storage key of the recording (`recordings/<environment>/<tenant_id>/<YYYY>/<MM>/<call_id>.wav`), or `null` if no recording. Not a download link: the public API does not serve recording audio
`recording_duration_seconds`	integer \| null	Recording length in seconds
`recording_size_bytes`	integer \| null	Recording file size in bytes
`recording_format`	string \| null	Recording container format: `wav`
`outcome`	string \| null	Call outcome label
`created_at`	string \| null	ISO-8601 record creation time
`updated_at`	string \| null	ISO-8601 last update time

Get Transcript

Retrieve the conversation transcript for a call as an ordered list of exchanges:

curl "https://apps.aurionai.net/api/v1/calls/9f1c8e3a-7b2d-4c5e-8f90-1a2b3c4d5e6f/transcript" \
  -H "X-API-Key: itsm_sk_live_xxxx"

An unknown or cross-tenant ID returns 404 {"detail": "Call not found"}. A call with no recorded exchanges returns an empty exchanges array.

Response:

{
  "call_id": "9f1c8e3a-7b2d-4c5e-8f90-1a2b3c4d5e6f",
  "exchanges": [
    {
      "sequence_number": 1,
      "user_transcript": "Hi, my VPN is not connecting since this morning.",
      "agent_response": "I can help with that. Let me check your account first.",
      "error": false,
      "error_message": null,
      "exchange_timestamp": "2026-03-08T10:30:12Z"
    }
  ]
}

Each exchange pairs the caller's transcribed speech (user_transcript) with the agent's reply (agent_response). error flags a failed turn, with error_message carrying the detail when present.

Get Recording

Retrieve the stored recording metadata for a call:

curl "https://apps.aurionai.net/api/v1/calls/9f1c8e3a-7b2d-4c5e-8f90-1a2b3c4d5e6f/recording" \
  -H "X-API-Key: itsm_sk_live_xxxx"

An unknown or cross-tenant ID returns 404 {"detail": "Call not found"}. A call that has no recording stored returns 404 {"detail": "Recording not available"}.

Response:

{
  "call_id": "9f1c8e3a-7b2d-4c5e-8f90-1a2b3c4d5e6f",
  "recording_url": "recordings/production/0b6e2c1d-4f3a-4e8b-9c7d-2a1b3c4d5e6f/2026/03/9f1c8e3a-7b2d-4c5e-8f90-1a2b3c4d5e6f.wav",
  "recording_format": "wav",
  "recording_size_bytes": 1482240,
  "recording_duration_seconds": 185
}

The recording_url is the recording's storage key, not a download link: the public API does not serve the recording audio.

Call Statuses

The status field is surfaced as stored on the call record. It is one of:

Status	Description
`ringing`	Call is ringing, not yet answered
`in_progress`	Call is in progress
`completed`	Call ended normally
`failed`	Call failed (network issue, timeout)
`no_answer`	Call was not answered

Webhook Events

Subscribe to call events via webhooks:

Event	Description
`call.started`	A voice call session started
`call.completed`	A voice call session ended
`call.escalated`	A call was escalated to a human agent

Voice Widget — Embed AI voice support on your website
Conversations — Voice calls linked to conversations
End-User API — Voice token generation for mobile app and widget
Webhooks — Subscribe to call.* events

Required Scope

All call endpoints require the calls:read scope on your API key.

Calls & Recordings

On this page