Recordings - Synthesys Docs

List call recordings, read their details and get a signed link to download the audio.

A recording belongs to one call log. Recordings are read-only. Their objects never contain an audio link, so use the download route to get a signed link that works without a login.

Endpoint	Request
List recordings	GET`/v1/recordings`
Get a recording	GET`/v1/recordings/{id}`
Get a recording download URL	GET`/v1/recordings/{id}/download-url`

The recording object

Fields are in snake_case.

Attributes

idstringrequired

The recording's UUID.

call_log_idstringrequired

The call_id of the call this recording belongs to.

titlestringrequired

The recording's title.

notesstringrequired

Notes on the recording.

statusstringrequired

processing, ready, failed or archived.

formatstringrequired

mp3, wav, mp4 or m4a.

qualitystringrequired

low, medium or high.

durationnumber | null

Length in seconds.

file_sizeinteger | null

File size.

ingested_atstring | null

When the audio file was stored.

transcription_enabledbooleanrequired

Whether transcription is enabled for this recording.

agent_idstring | null

The agent on the call.

agent_display_namestring | null

The agent's display name.

provider_call_idstring | null

The voice provider's ID for this call. Quote it when you ask about a call.

call_directionstring

inbound or outbound.

call_typestring

The type of call, such as outboundPhoneCall, inboundPhoneCall, webCall or websocketCall.

is_test_callboolean

Whether this was a test call.

customer_phonestring | null

The contact's phone number. Can be N/A - web call for web and test calls.

call_started_atstring | null

When the call started, as an ISO 8601 timestamp.

call_statusstring | null

The call's status. Returned by List recordings only.

call_ended_reasonstring | null

Why the call ended. Returned by List recordings only. See Ended reasons.

recording_urlnullrequired

Always null. Use the download route instead.

stereo_recording_urlnullrequired

Always null. Use the download route instead.

created_atstringrequired

When the recording was created, as an ISO 8601 timestamp.

updated_atstringrequired

When the recording last changed, as an ISO 8601 timestamp.

Returns your recordings, newest first. Send page or limit to page through them, with pagination in the response. With neither, you get every recording, with no pagination and no provider_call_id, so send limit for those.

Query parameters

call_log_idstring

Only return recordings for this call's call_id.

pageintegerdefault 1

The page to return, from 1 to 1,000,000.

limitintegerdefault 50

Results per page, from 1 to 100.

Errors

Status	When
`400`	`call_log_id`, `page` or `limit` is invalid. `details.issues` names the field.

Request

curl "https://backend.synthesys.app/api/v1/recordings?call_log_id=1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d" \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "id": "3f1c9e7a-2d4b-4c6e-8a1f-5b7d9c3e1a2f",
      "call_log_id": "1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
      "title": "Call with Jane",
      "notes": "",
      "status": "ready",
      "format": "mp3",
      "quality": "medium",
      "duration": 184,
      "file_size": 2944000,
      "ingested_at": "2026-10-31T14:06:02.000Z",
      "transcription_enabled": true,
      "agent_id": "6f1d2a34-8b7c-4e21-9a10-3c5d7e9f1b20",
      "agent_display_name": "Sales Agent",
      "call_direction": "outbound",
      "call_type": "outboundPhoneCall",
      "is_test_call": false,
      "customer_phone": "+12025550123",
      "call_started_at": "2026-10-31T14:02:16.000Z",
      "call_status": "ended",
      "call_ended_reason": "customer-ended-call",
      "recording_url": null,
      "stereo_recording_url": null,
      "created_at": "2026-10-31T14:05:25.000Z",
      "updated_at": "2026-10-31T14:06:02.000Z",
      "provider_call_id": "2e4f6a8c-1b3d-4f5a-9c7e-0d2b4f6a8c1e"
    }
  ],
  "pagination": { "total": 1, "page": 1, "limit": 50, "totalPages": 1 }
}

Get a recording

GET/v1/recordings/{id}read key

Returns one recording.

Path parameters

idstringrequired

The recording's UUID.

Errors

Status	When
`400`	The ID isn't a valid UUID.
`404`	No recording with this ID exists on your account. `error` is `Recording not found`.

Request

curl https://backend.synthesys.app/api/v1/recordings/3f1c9e7a-2d4b-4c6e-8a1f-5b7d9c3e1a2f \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "id": "3f1c9e7a-2d4b-4c6e-8a1f-5b7d9c3e1a2f",
    "call_log_id": "1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
    "title": "Call with Jane",
    "notes": "",
    "status": "ready",
    "format": "mp3",
    "quality": "medium",
    "duration": 184,
    "file_size": 2944000,
    "ingested_at": "2026-10-31T14:06:02.000Z",
    "transcription_enabled": true,
    "agent_id": "6f1d2a34-8b7c-4e21-9a10-3c5d7e9f1b20",
    "agent_display_name": "Sales Agent",
    "call_direction": "outbound",
    "call_type": "outboundPhoneCall",
    "is_test_call": false,
    "customer_phone": "+12025550123",
    "call_started_at": "2026-10-31T14:02:16.000Z",
    "recording_url": null,
    "stereo_recording_url": null,
    "created_at": "2026-10-31T14:05:25.000Z",
    "updated_at": "2026-10-31T14:06:02.000Z",
    "provider_call_id": "2e4f6a8c-1b3d-4f5a-9c7e-0d2b4f6a8c1e"
  }
}

Get a recording download URL

GET/v1/recordings/{id}/download-urlread key

Returns a signed link to the recording's audio. The link works without an API key or a login until it expires, so fetch it from your server and treat it as a secret.

Path parameters

idstringrequired

The recording's UUID.

Query parameters

typestringdefault mono

mono or stereo.

dispositionstringdefault attachment

attachment to download the file, or inline to play it in place.

Response data

urlstringrequired

The signed link. Its address can change, so don't parse it.

typestringrequired

The audio you're getting, mono or stereo. If the recording doesn't have the type you asked for, you get the other one, and this field says so.

dispositionstringrequired

The disposition you requested.

expiresInSecondsintegerrequired

How long the link lasts. Currently 3600.

expiresAtstringrequired

When the link expires, as an ISO 8601 timestamp.

Request a new link when one expires, rather than storing it.

Errors

Status	Code	When
`400`	`VALIDATION_ERROR`	`type` or `disposition` isn't an allowed value, or the ID isn't a valid UUID.
`404`	`NOT_FOUND`	No recording with this ID exists on your account.
`409`	`RECORDING_NOT_READY`	The recording's `status` isn't `ready`, or its audio file isn't available. Check again shortly.

Request

curl "https://backend.synthesys.app/api/v1/recordings/3f1c9e7a-2d4b-4c6e-8a1f-5b7d9c3e1a2f/download-url?type=stereo" \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "url": "https://example.com/signed/recording.mp3?token=SIGNED_TOKEN",
    "type": "stereo",
    "expiresInSeconds": 3600,
    "expiresAt": "2026-10-31T15:10:00.000Z",
    "disposition": "attachment"
  }
}

Not ready (409)

{
  "success": false,
  "error": "The recording is not ready to download yet.",
  "code": "RECORDING_NOT_READY",
  "requestId": "e3a1c5d7-2b4f-4a6c-9d8e-1f2a3b4c5d6e",
  "timestamp": "2026-10-31T14:06:00.000Z"
}