Recording resource

A Recording is the captured audio of a call, stored under your retention policy with AES-256-GCM envelope encryption at rest. Recordings are produced when a call is created with record enabled or when a call-control document records mid-call. You retrieve the audio through a short-lived signed URL — issued only on fetch and audited — and you can list, inspect or delete recordings through the API.

Properties

The media_url is a short-lived signed URL issued only when you fetch a single recording; fetch the audio promptly and do not cache the URL. Every access is written to the append-only audit trail.

Status enum

The status field reports where a recording is in its lifecycle. The same values are delivered as recording_status on the callback below.

Fetch a recording

Retrieve a single recording by its SID. The response includes a short-lived signed media_url for the audio.

# illustrative — shape may differ at GA
curl https://api.telvox.dev/v1/recordings/RE2a7f9c1d4b6e8a0c3f5d7b9e1a2c4d6 \
  -H "Authorization: Bearer $TELVOX_API_KEY"

// illustrative — shape may differ at GA
{
  "object": "recording",
  "sid": "RE2a7f9c1d4b6e8a0c3f5d7b9e1a2c4d6",
  "call_sid": "CA8f0e1d7c4b2a9f6e3d0c1b8a7f6e5d4",
  "status": "completed",
  "duration": 47,
  "channels": 2,
  "format": "mp3",
  "encryption": "aes-256-gcm",
  "storage_backend": "s3",
  "media_url": "https://api.telvox.dev/media/RE2a7f…?sig=…&exp=1750612951",
  "retention_until": "2026-12-22T00:00:00Z",
  "created_at": "2026-06-22T17:04:58Z"
}

List recordings

Return a paginated list of recordings, newest first, narrowed by the filters below. Signed media URLs are omitted from lists — fetch an individual recording to obtain one. See pagination for cursoring.

# illustrative — shape may differ at GA
curl "https://api.telvox.dev/v1/recordings?call_sid=CA8f0e1d7c4b2a9f6e3d0c1b8a7f6e5d4" \
  -H "Authorization: Bearer $TELVOX_API_KEY"

// illustrative — media_url is omitted from lists; fetch a recording to get one
{
  "object": "list",
  "url": "/v1/recordings",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "object": "recording",
      "sid": "RE2a7f9c1d4b6e8a0c3f5d7b9e1a2c4d6",
      "call_sid": "CA8f0e1d7c4b2a9f6e3d0c1b8a7f6e5d4",
      "status": "completed",
      "duration": 47,
      "channels": 2,
      "format": "mp3"
    }
  ]
}

Delete a recording

Permanently delete a recording and its encrypted media. The deletion is recorded in the audit trail and cannot be undone.

# illustrative — shape may differ at GA
curl -X DELETE \
  https://api.telvox.dev/v1/recordings/RE2a7f9c1d4b6e8a0c3f5d7b9e1a2c4d6 \
  -H "Authorization: Bearer $TELVOX_API_KEY"

// illustrative — no response body
HTTP/1.1 204 No Content

RecordingStatusCallback

Set a recording_status_callback when you start recording and Connect POSTs to that URL as the recording moves through its lifecycle. Respond 2xx promptly. Delivery is over the same signed, SSRF-safe egress that powers Dial — see webhooks & callbacks for signature verification.

Callback payload

// illustrative — POST body delivered to your recording_status_callback
{
  "recording_sid": "RE2a7f9c1d4b6e8a0c3f5d7b9e1a2c4d6",
  "call_sid": "CA8f0e1d7c4b2a9f6e3d0c1b8a7f6e5d4",
  "recording_status": "completed",
  "duration": 47,
  "channels": 2,
  "timestamp": "2026-06-22T17:05:01Z"
}