Download a call recording
curl --request GET \
--url https://api.healos.ai/ext-api/v1/receptionist/calls/{callId}/recording \
--header 'X-API-Key: <api-key>'const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.healos.ai/ext-api/v1/receptionist/calls/{callId}/recording', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.healos.ai/ext-api/v1/receptionist/calls/{callId}/recording"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)"<string>"{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "Rate limit exceeded. Please retry after the window resets.",
"code": "daily_cap_reached",
"reset_at": "2026-10-28T00:00:00.000Z"
}{
"error": "<string>"
}{
"error": "<string>"
}Receptionist
Download a call recording
The call’s recording as audio bytes (usually audio/mpeg), streamed through the API; there is no public media URL. Every download is written to the organization’s recording access log before the audio is sent, with the key owner as the accessor. 404 when the call has no recording (has_recording is false on the call), 502 when the stored recording could not be read. Requires the receptionist:read scope.
GET
/
receptionist
/
calls
/
{callId}
/
recording
Download a call recording
curl --request GET \
--url https://api.healos.ai/ext-api/v1/receptionist/calls/{callId}/recording \
--header 'X-API-Key: <api-key>'const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.healos.ai/ext-api/v1/receptionist/calls/{callId}/recording', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.healos.ai/ext-api/v1/receptionist/calls/{callId}/recording"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)"<string>"{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "Rate limit exceeded. Please retry after the window resets.",
"code": "daily_cap_reached",
"reset_at": "2026-10-28T00:00:00.000Z"
}{
"error": "<string>"
}{
"error": "<string>"
}| Requirement | Detail |
|---|---|
| Scope | receptionist:read |
| Rate limit | About 60 requests per minute per API key (shared by all endpoints; approximate) |
| Cost | Free |
Safety
- Writes data: No (an entry is added to your organization’s recording access log on every download)
- Safe to retry: Yes
- Contacts an outside system: Reads the stored recording from HealOS storage or the voice provider
- Dry run: Not needed (read-only).
Content-Type is the stored media type (usually audio/mpeg) and Content-Disposition names the file call-<callId>.mp3. There is no public media URL: the bytes are streamed through the API, so the request needs your key like any other.
Check has_recording on the call before downloading; a call without one answers 404. The recording length is the call’s duration_sec.
Every download is written to the organization’s recording access log before any audio is sent, with the API key’s owner as the accessor, the same way dashboard downloads are logged. If that log cannot be written the download is refused with 503.
curl -sS "https://api.healos.ai/ext-api/v1/receptionist/calls/$CALL_ID/recording" \
-H "X-API-Key: $HEALOS_API_KEY" \
-o "call-$CALL_ID.mp3"
Authorizations
API key obtained from /api/v1/ext-api-keys
Path Parameters
Call identifier, from GET /receptionist/calls or the post-call webhook's call_id.
Example:
"c0a80101-0000-4000-8000-000000000001"
Response
The recording. Content-Disposition names the file call-<callId>.mp3; Content-Type is the stored media type.
The response is of type file.
Was this page helpful?