Skip to main content
GET
Get Call Recordings Endpoint
This endpoint is in beta. The interface is stable enough to build on; we may add fields as it matures.

Overview

Pull the calls placed to a given number in your workspace, newest first, each with its timing details and a recording download URL. Use it to fetch all recordings for a lead or just the latest one, straight into your own system. Recording is on by default for every workspace — there is nothing to enable. Every outbound call that connects is recorded automatically, and the audio is available a few seconds after the call ends. To list every recording in your workspace rather than the calls to one lead, see List recordings & uploads.

Making a request

  • Method: GET
  • URL: https://app.tuco.ai/api/voice/recordings
  • Headers: Authorization: Bearer tuco_...

Query parameters

string
required
The lead’s phone number, E.164 (e.g. +13025550123).URL-encode the + as %2B. In a query string a raw + means a space, and calls are matched on the exact E.164 string — so ?number=+13025550123 looks up 13025550123, matches nothing, and returns 200 with "count": 0. The Try it panel encodes this for you; hand-written requests must do it themselves.
string
Alias for number. Accepted interchangeably; supply one or the other.
boolean
Return only the most recent call to that number.
boolean
Return only calls that have a recording URL.
number
Max calls to return. Default 20, max 100. Ignored when latest=true.

Response

Calls are returned newest first. Each entry includes timing details and the recording download URL (recordings resolve after a call ends).
string
The number you queried.
number
Number of calls returned.
array
The calls, newest first.
You only ever see calls in your own workspace. Recordings resolve a few seconds after a call ends; a null recordingUrl on a live or very recent call is expected.

Recording URLs expire

recordingUrl is a signed link that expires 30 days after you fetch it. Do not store the URL — store the callId and call this endpoint again when you need the audio. A saved URL will start returning an error once it lapses.
Each call returns a fresh link, so re-requesting is the supported way to get a working URL. The audio itself is kept indefinitely; only the link is time-limited.

When a recording exists

A recording only exists for a call that connected. Specifically:
  • Recording starts the moment the call is answered, so unanswered, busy and failed calls have no audio and return recordingUrl: null.
  • A call answered and dropped within a second or two may also have no audio — the recording had not started yet.
  • Audio is MP3, mono. Both sides of the conversation are mixed into a single channel, so the format is suited to playback and transcription, but not to separating the speakers.

Automatic CRM sync

If your workspace has HubSpot connected, you do not need this endpoint to get recordings into your CRM. When a call ends, Tuco writes a note to that contact’s HubSpot timeline containing a play link, timestamped to the time of the call. Nothing to configure. Use this endpoint when you want the audio in your own system — a data warehouse, a transcription pipeline, or a CRM other than HubSpot.

Errors