> ## Documentation Index
> Fetch the complete documentation index at: https://docs.healos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

| Requirement | Detail |
| - | - |
| **Scope** | `receptionist:read` |
| **Rate limit** | About 60 requests per minute per API key (shared by all endpoints; approximate) |
| **Cost** | Free |

> [!TIP]
>
> **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).

The response body is the audio itself, not JSON. `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`.

```bash theme={null}
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"
```

Guide: [Receptionist call transcripts](https://docs.healos.ai/recipes/receptionist-call-transcripts.md). Errors: [Error catalog](https://docs.healos.ai/errors.md).


## OpenAPI

````yaml openapi/ext-api-v1.json GET /receptionist/calls/{callId}/recording
openapi: 3.0.0
info:
  title: Healos External API
  version: 1.0.0
  description: >-
    External API for managing patients, documents, and appointments, listing
    providers and note templates, pulling clinical notes (with transcript and
    patient context), running insurance eligibility checks, browsing the EHR
    action catalog, reading AI Receptionist calls (summary, transcript,
    extracted details and recording), managing the AI Receptionist inbox tasks,
    and registering webhooks for note and document events.
servers:
  - url: https://api.healos.ai/ext-api/v1
    description: Production
  - url: http://localhost:8787/ext-api/v1
    description: Local development
security:
  - ApiKeyAuth: []
paths:
  /receptionist/calls/{callId}/recording:
    get:
      tags:
        - Receptionist
      summary: Download a call recording
      description: >-
        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.
      parameters:
        - schema:
            type: string
            description: >-
              Call identifier, from GET /receptionist/calls or the post-call
              webhook's `call_id`.
            example: c0a80101-0000-4000-8000-000000000001
          required: true
          name: callId
          in: path
      responses:
        '200':
          description: >-
            The recording. `Content-Disposition` names the file
            `call-<callId>.mp3`; `Content-Type` is the stored media type.
          content:
            audio/mpeg:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient scope (needs receptionist:read)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Call not found, or the call has no recording
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '502':
          description: The recording exists but could not be read from storage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The access log could not be written, so the recording was not served
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
    RateLimitError:
      type: object
      properties:
        error:
          type: string
          example: Rate limit exceeded. Please retry after the window resets.
        code:
          type: string
          enum:
            - daily_cap_reached
          description: >-
            Set when the organization reached its daily cap for this paid
            operation (not on a per-minute limit).
        reset_at:
          type: string
          format: date-time
          description: 'With `code`: when the daily cap resets (next 00:00 UTC).'
          example: '2026-10-28T00:00:00.000Z'
      required:
        - error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key obtained from /api/v1/ext-api-keys

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.