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

# Download Ambient Session Audio

> Learn how to download the original audio recording from an Ambient session for playback, verification, and compliance

<div className="quick-summary-wrapper">
  <div className="quick-summary-header">
    <span className="quick-summary-icon" aria-hidden="true" />

    <span className="quick-summary-title">Quick summary</span>
  </div>

  <div className="quick-summary-content">
    Get secure, temporary access to the original audio from <Tooltip tip="A single, time-bound instance of an ambient recording for a specific patient encounter that captures clinical conversations." cta="View in Glossary" href="/Glossary/a">ambient sessions</Tooltip>. Use it to play back recordings in your app, verify notes against the conversation, or save files for compliance.
  </div>

  <div className="quick-summary-footer">
    <span className="quick-summary-footer-icon" aria-hidden="true" />

    <span className="quick-summary-footer-text">Last updated:</span>
    <span className="quick-summary-footer-date">July 2026</span>
  </div>
</div>

<Info>
  **Download session audio is supported by:** Ambient APIs
</Info>

In an ambient workflow, you can use the [Get session recording API](/api-reference/ambient-content/recording) to download the original audio from a session. This recording is the raw conversation captured during the visit.

Ambient sessions already generate <Tooltip tip="The text version of recorded audio from clinical conversations, generated by automatic speech recognition." cta="View in Glossary" href="/Glossary/t">transcripts</Tooltip>, notes, and <Tooltip tip="Organized medical information extracted from clinical conversations, formatted for integration with EHR systems." cta="View in Glossary" href="/Glossary/s">structured data</Tooltip>. This API gives you access to the source audio so you can play it in your app, verify AI-generated outputs, or store it for compliance.

You request a recording URL from the Audio Streaming & Download API. The URL lets you either **stream** the audio (for playback with seeking) or **download** the full file.

<Warning>
  URLs are temporary and expire after a short time for security.
</Warning>

## Common integration patterns and use cases

Design session audio access around whether your application needs in-app playback, note verification, or longer-term storage. Request a temporary recording URL from the ambient recording API, then stream or download the WAV file before the URL expires.

The following patterns show common ways to use session audio download:

<CardGroup cols={2}>
  <Card title="In-App Visit Playback" icon="play">
    Call the recording API with `download=false`, then stream the WAV URL in your player so clinicians can seek and scrub.
  </Card>

  <Card title="Verify Notes Against Audio" icon="ear-listen">
    Load the session recording next to the note or transcript UI so clinicians can jump to the relevant part of the visit.
  </Card>

  <Card title="Archive Audio for Compliance" icon="shield-check">
    Request the recording with `download=true` within the 7-day availability window and store the WAV in your own system.
  </Card>

  <Card title="Playback for Uploaded Sessions" icon="cloud-arrow-up">
    After an uploaded session completes, use the same recording API. If you receive a temporary 404, wait for processing and retry.
  </Card>

  <Card title="Multi-Chunk Recordings" icon="layer-group">
    Read the `recordings` array and use `sequence_number` to play or assemble chunks in order.
  </Card>

  <Card title="Refresh Expired Playback URLs" icon="rotate">
    Watch `expires_at`. When the URL expires mid-playback, call the recording endpoint again for a fresh URL.
  </Card>
</CardGroup>

## Recording access benefits

<CardGroup cols={2}>
  <Card title="Stream for Playback" icon="microphone">
    Stream audio in your app. Supports seeking and scrubbing so users can jump to any part of the recording.
  </Card>

  <Card title="Download for Storage" icon="download">
    Download the full audio file when you need to keep it for archival or compliance.
  </Card>

  <Card title="Works for All Sessions" icon="globe">
    Available for both real-time streamed sessions and sessions where audio was uploaded after the visit.
  </Card>

  <Card title="Time-Limited Access" icon="lock">
    Streaming URLs last 15 minutes for short sessions, or session length plus 10 minutes for long sessions. Download URLs last 1 hour.
  </Card>

  <Card title="7-Day Availability" icon="clock">
    Recordings are available for 7 days after the session. After that, they are no longer accessible.
  </Card>

  <Card title="Access Logging" icon="file-text">
    Each access is logged for compliance and security.
  </Card>

  <Card title="WAV Format" icon="file">
    Recordings are returned in WAV format, ready for playback in standard media players.
  </Card>
</CardGroup>

## How recording retrieval works

1. **Finish an ambient session**: Create a session, stream or upload audio, and end it. The recording is ready once the session is complete.
2. **Request a recording URL**: Call the recording API with your `session ID`. Choose streaming (for playback) or download (for saving the file). Some sessions may return multiple recordings; use the one you need.
3. **Use the URL**: Stream or download the audio in WAV format. If the response indicates streaming is not supported, use download mode instead. If the URL expires while someone is listening, request a **new one**.

### Workflow

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart TD
    A[Ambient session complete] --> B[Request recording URL]
    B --> C{Need to play or save?}
    C -->|Play in app| D[Streaming]
    C -->|Save file| E[Download]
    D --> F[Get URL]
    E --> F
    F --> G[Stream/Download audio]
    G --> H[URL expires]
    
    style A fill:#FFF394,stroke:#333,color:#000
    style B fill:#FFF394,stroke:#333,color:#000
    style C fill:#FFF394,stroke:#333,color:#000
    style D fill:#FFF394,stroke:#333,color:#000
    style E fill:#FFF394,stroke:#333,color:#000
    style F fill:#FFF394,stroke:#333,color:#000
    style G fill:#FFF394,stroke:#333,color:#000
    style H fill:#FFF394,stroke:#333,color:#000
```

## How to use the Download API

<Steps>
  <Step title="Complete an Ambient Session">
    Create an ambient session, stream or upload audio, and end the session. The recording is available after the session is complete.

    Use the [Create ambient session API](/api-reference/ambient-sessions/create) to create an ambient session.
  </Step>

  <Step title="Request the Recording URL">
    Call the [Recording API endpoint](/api-reference/ambient-content/recording) with your ambient `session ID`. Use the `download` parameter: `false` for streaming (playback) or `true` for full file download.
  </Step>

  <Step title="Stream or Download">
    Use the returned URL to stream or download the audio (WAV format).

    <Warning title="URL Expiration">
      **URL Expiration**:

      The recording URL is available for a limited time. You need to request a new URL when it expires.

      * **Streaming**: The URL lasts 15 minutes for short sessions. For sessions longer than 15 minutes, it lasts long enough to play the full recording (session length plus 10 minutes).
      * **Download**: The URL lasts 1 hour.
    </Warning>

    <Note title="Recording availability">
      **How long are recordings kept?**

      **7 days** from the session date. After that, the recording is no longer available.
    </Note>
  </Step>

  <Step title="Request a New URL When Needed">
    If the URL expires during playback, call the recording endpoint again to get a fresh URL.
  </Step>
</Steps>

## Response structure for Download API

When the request succeeds, the API returns a `recordings` array. Each item in the array represents one recording chunk for the session.

<ResponseField name="recordings" type="array">
  List of recordings for the session. Each item contains a presigned URL and metadata.

  <Expandable title="recording item fields">
    <ResponseField name="recording_id" type="string">
      Unique identifier for the recording.
    </ResponseField>

    <ResponseField name="presigned_url" type="string">
      Temporary URL to stream or download the recording. This URL expires; see expiry times in the steps above.
    </ResponseField>

    <ResponseField name="expires_at" type="integer">
      Unix timestamp when the presigned URL expires. Use this to know when to request a new URL.
    </ResponseField>

    <ResponseField name="sequence_number" type="integer">
      The order of this recording chunk within the session. Sessions can have multiple recordings; use `sequence_number` to play or assemble them in the correct order.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="is_streamable" type="boolean">
  Whether the returned URLs support streaming with Range requests. If `false`, use `download=true` to get a download URL instead.
</ResponseField>

## Best practices

<Tip>
  * **Stream for playback**: Use streaming when building a player so users can seek to any part of the recording
  * **Download for archival**: Use download when you need to store the file long-term
  * **Handle 404 on uploaded sessions**: If you get 404 for a session where audio was uploaded, the recording may still be processing. Wait and retry
  * **Do not retry on 410**: When you get 410, the recording is permanently unavailable
  * **Refresh URLs when needed**: For streaming, the URL lasts 15 minutes or session duration plus 10 minutes for long sessions. Request a new URL when it expires
  * **Use access responsibly**: All access is logged; ensure your use meets your compliance requirements
</Tip>

## FAQs

<Accordion title="What Is the Difference Between Streaming and Download?">
  | Mode      | Use case                                          | URL expires                                                             |
  | :-------- | :------------------------------------------------ | :---------------------------------------------------------------------- |
  | Streaming | Play audio in your app with seeking and scrubbing | 15 min for short sessions; session length plus 10 min for long sessions |
  | Download  | Save the full file for archival or compliance     | 1 hour                                                                  |
</Accordion>

<Accordion title="Why Does the Streaming URL Last Longer for Long Sessions?">
  For sessions longer than 15 minutes, the streaming URL is valid for the full session length plus 10 minutes. This lets you play the entire recording without the URL expiring mid-playback.
</Accordion>

<Accordion title="What Audio Format Is Returned?">
  Recordings are returned in WAV format. Use them in standard media players or HTML5 audio elements for playback.
</Accordion>

<Accordion title="Can a Session Have Multiple Recordings?">
  Yes. Some sessions may return multiple recordings. The API returns a list; use the recording that matches your needs. If the response indicates streaming is not supported for a recording, use download mode instead.
</Accordion>

<Accordion title="How Long Are Recordings Available?">
  Recordings are available for 7 days from the session date. After that, the recording is no longer accessible. If you need to keep the audio longer, download it within the 7-day window and store it in your own system.
</Accordion>

<Accordion title="What If I Get 404 When Requesting a Recording?">
  For sessions where audio was uploaded (not streamed in real time), the recording may still be processing. Wait a moment and try again. If the session is older than 7 days, you will get 410 instead, which means the recording is permanently unavailable.
</Accordion>