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

# Work with Multiple Recordings

> Offer listen-back or downloading capabilities for ambient session generated audio after the visit is complete using temporary presigned URLs from the Recording API

<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">
    Suki provides transcripts, note content, and structured data from every ambient session. When your product also needs the source audio, fetch temporary presigned URLs after the session ends.

    <br />

    <br />

    Use the Recording API to offer listen-back or downloading capabilities for ambient session generated audio after the visit is complete using temporary presigned URLs.
  </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">August 2026</span>
  </div>
</div>

<Info>
  **Ambient session recordings are supported by:** Ambient APIs
</Info>

Suki provides transcripts, clinical notes, and structured data for Ambient sessions. If your workflow also requires access to the **source audio**, you can retrieve the recording using the [Get Ambient session recording](/api-reference/ambient-content/recording) API.

The API returns a **temporary presigned URL** for the session recording. Your application can use the URL to play or download the recording in **WAV** format.

Audio retrieval is **optional**. You do not need to retrieve the recording to:

* End an Ambient session
* Retrieve Ambient content
* Approve a note
* Save a note to an EHR

Use audio retrieval only when your application needs to provide clinicians or other authorized users with access to the source recording.

## When to add listen-back or downloading capabilities to your application

Integrate Recording API into your application's note review flow when your organization requires it to help clinicians:

* Review a section of the conversation when the generated note does not look right.
* Verify what was said without leaving the patient chart.
* Support an existing audit or compliance workflow that requires access to the source recording.
* Meet organizational requirements or service-level agreements that require access to recorded audio.

## What your application needs to handle

If you add Recording API to your product, your application should handle:

* **Listen-back controls:** Add a **listen** or **playback** action button where clinicians review the note or visit. Keep this separate from the live recording experience.
* **Recording URL retrieval:** Retrieve the recording URL using the [Get Ambient session recording](/api-reference/ambient-content/recording) API when the audio is available.
* **Temporary URL handling:** Presigned URLs expire after a short time. Each item in `recordings` includes `expires_at` so your application knows when the URL is no longer valid. When the URL expires or playback fails, call [Get Ambient session recording](/api-reference/ambient-content/recording) again for a new URL. See [URL validity and refresh](#url-validity-and-refresh) for expiry times and refresh rules.
* **Access control:** Restrict access for downloading or listening to the recording according to your application's authorization model and the user's access level.

## URL validity and refresh

Each presigned URL is valid for a limited time. The [Get Ambient session recording](/api-reference/ambient-content/recording) response includes `expires_at` (Unix timestamp) on every item in `recordings`. Use it to refresh before playback fails, or to recover when a player request returns an error.

| Mode                                      | When the URL expires                                                                                |
| :---------------------------------------- | :-------------------------------------------------------------------------------------------------- |
| Streaming (`download` omitted or `false`) | 15 minutes for short sessions. For sessions longer than 15 minutes, session length plus 10 minutes. |
| Download (`download=true`)                | 1 hour                                                                                              |

<Note>
  The **recording file** stays available for **7 days** from the session date. After that window, the API returns **410** and you cannot retrieve new URLs for that session. If your organization needs long-term storage, download the WAV within 7 days and store it in your own system.
</Note>

### Recommended flow for integration

* Call [Get Ambient session recording](/api-reference/ambient-content/recording) API asynchronously when the clinician opens your listen-back or downloading capabilities action button or when your archive job runs, not long before, and cache the URL for later.
* Watch `expires_at` on each item in `recordings`. Request a new URL before it passes, or immediately when playback or download fails.
* When a presigned URL expires, call the recording endpoint again with the same `ambient_session_id`. Use the new `presigned_url` and the same `download` mode (stream or full file) you used before.
* On **404**, wait and retry. The recording may still be processing (common for uploaded audio).
* On **410**, stop retrying. The session is past the 7-day retention window.
* If `is_streamable` is `false`, call the endpoint again with `download=true` instead of using streaming mode.
* For multi-chunk sessions, refresh per chunk in `recordings` and use `sequence_number` to keep playback order.

### Wrong behavior

* Do not save presigned URLs as permanent chart links, EHR fields, or shared URLs. They expire and will break for other users.
* Do not treat **404** the same as **410**. **404** can be temporary; **410** means the recording is gone for good.
* Do not keep retrying the recording API after **410**. No new URL will be issued for that session.
* Do not use streaming URLs when `is_streamable` is `false`. Request `download=true` instead.
* Do not block approve, sign, or chart save on a successful recording fetch. Audio listen-back is optional.
* Do not assume the presigned URL outlives the recording file. Even a fresh URL only works while the session is within the 7-day window.

<Note>
  Suki logs each recording access for compliance and security. Ensure your use meets your organization's compliance requirements.
</Note>

**Recording rules (agents):**

* Recordings are optional. Never require audio playback for End, content retrieval, approve, or chart save.
* Many products only need transcript and note content. Add recordings only when clinicians must hear the conversation, or when compliance requires archiving source audio.
* Place Listen on note review or audit after Ambient ends. Do not mix playback with the live Start Ambient mic control.
* Presigned URLs are temporary. Watch `expires_at`. Refresh by calling the recording endpoint again. Do not treat URLs as permanent chart links. URL expiry times and 7-day retention are in [URL validity and refresh](#url-validity-and-refresh).
* Use streaming URLs (`download` omitted or `false`) for in-app players. Use `download=true` when you need the full file for archive.
* Enforce access control: only users who may hear that visit's audio.
* Handle **404** on uploaded sessions (processing): wait and retry. Do not retry on **410** (retention expired).

## What you need to decide before you build

Before building a listen-back or recording download feature, consider whether your workflow actually requires access to the source audio.

For most chart review workflows, **transcripts and note content are sufficient**. Add source audio when clinicians need to listen to the original visit recording or when your organization needs to retain the recording as a **WAV file** for an approved workflow.

<AccordionGroup>
  <Accordion title="Do You Need Audio or Only the Transcript?" icon="waveform">
    Most products only need the [Transcript](/api-reference/ambient-content/transcript) and note content from [Load the note](/documentation/how-to/ambient-clinical-notes/retrieve-ambient-content). Add source audio when clinicians need to listen to the original conversation or when your workflow requires source audio to be archived.
  </Accordion>

  <Accordion title="Stream the Recording or Download the File" icon="download">
    Use a streaming URL (`download` omitted or `false`) when your application plays the recording in an audio player. Use `download=true` when your application needs to retrieve the complete WAV file, such as for an approved archival workflow.
  </Accordion>

  <Accordion title="Where Should Playback Appear" icon="browser">
    Add **Listen** to the note review or audit experience after the Ambient session ends. Avoid placing playback controls next to **Start Ambient** on the live visit screen, where the recording is still in progress.
  </Accordion>

  <Accordion title="Who Can Access the Recording" icon="shield">
    Restrict playback and downloads to users who are authorized to access the visit's audio. Treat recording URLs as protected clinical media and apply the same access controls you use for other sensitive clinical content.
  </Accordion>
</AccordionGroup>

<Tip>
  Treat recordings as secondary to the note workflow. Do not make this mandatory for approve, sign, or chart save.
</Tip>

## Common 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, then stream or download the WAV file before the presigned URL expires.

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

## How recordings fit the visit

Recording access runs parallel to note retrieval. After the ambient session ends and processing completes, your application can fetch presigned URLs while the clinician reviews the note. Approve, sign, and save to the EHR do not depend on playback.

| What you offer           | How it helps                                                                  |
| :----------------------- | :---------------------------------------------------------------------------- |
| In-app listen-back       | Clinicians verify disputed or unclear note sections without leaving the chart |
| Download or archive      | Compliance or storage workflows that need the source WAV file                 |
| Transcript and note only | Faster chart review when hearing the visit is not required                    |

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFF394','primaryTextColor':'#111827','primaryBorderColor':'#FFE148','lineColor':'#FFE148','secondaryColor':'#FFF394','tertiaryColor':'#FFFADE','mainBkg':'#FFF394','secondBkg':'#FFFADE','tertiaryBorderColor':'#FFE148','border1':'#FFE148','border2':'#FFE148','arrowheadColor':'#FFE148','fontFamily':'Inter, system-ui, sans-serif','fontSize':'14px','nodeBorder':'#FFE148','edgeLabelBackground':'#FFE148','clusterBkg':'#FFFADE','clusterBorder':'#FFE148','defaultLinkColor':'#FFE148','titleColor':'#111827','nodeTextColor':'#111827'}}}%%
flowchart LR
    A["Ambient session<br/>ended"] --> B["GET recording<br/>URLs"]
    B --> C["Stream or<br/>download"]
    C --> D["Listen-back or<br/>archive UI"]
    A --> E["Retrieve note /<br/>transcript"]
    E --> F["Approve or<br/>save"]
    D --> F

    style A fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style B fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style C fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style D fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style E fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style F fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
```

## Recommended UI patterns

Place Listen on the same screen where the clinician reviews the generated note or runs an audit. Keep playback separate from the live Ambient recorder.

<Steps>
  <Step title="Show Note Review First">
    Open note review after Ambient ends and content is available. Let the clinician read the note before offering audio.
  </Step>

  <Step title="Show an Optional Listen Control">
    Place **Listen** near note review or audit actions. Do not place it next to Start Ambient on the live visit screen.
  </Step>

  <Step title="Fetch a Temporary URL on Demand">
    When the clinician taps Listen, call [Get Ambient session recording](/api-reference/ambient-content/recording). Pass the presigned URL to your player. Choose stream vs download with the `download` query parameter.
  </Step>

  <Step title="Refresh If the URL Expires">
    Watch `expires_at`. If playback fails because the URL expired, call the recording endpoint again for a fresh URL. See [URL validity and refresh](#url-validity-and-refresh).
  </Step>
</Steps>

<Warning>
  Presigned URLs expire on the schedule in [URL validity and refresh](#url-validity-and-refresh). Do not treat them as permanent chart links. When playback fails or `expires_at` has passed, call the recording endpoint again for a fresh URL.
</Warning>

| UI element         | What the clinician sees                  | Your application responsibility                              |
| :----------------- | :--------------------------------------- | :----------------------------------------------------------- |
| Listen / Playback  | Optional control on note review or audit | Fetch a fresh presigned URL; enforce who may hear the visit  |
| In-app player      | Streamed visit audio                     | Use streaming URLs; refresh when the URL expires             |
| Download / archive | Full WAV when required                   | Use `download=true`; store only under your compliance policy |
| Skip listen        | Continue without audio                   | Allow approve or save without playback                       |

## Implement Recording API in your application

<Steps>
  <Step title="Finish Ambient Capture">
    End the session and confirm processing as needed. Recording access applies to the ambient session you already captured. See [Complete an ambient visit](/documentation/how-to/ambient-clinical-notes/end-ambient-session).
  </Step>

  <Step title="Fetch Presigned URLs">
    Call [Get Ambient session recording](/api-reference/ambient-content/recording) when the clinician opens Listen or your archive job runs. Use the `download` parameter: omitted or `false` for streaming (playback), `true` for full file download.
  </Step>

  <Step title="Play or Store in Your Product">
    Use the temporary URL in your player or archive path. If the response includes multiple items in `recordings`, use `sequence_number` to play or assemble chunks in order. If `is_streamable` is `false`, request URLs with `download=true`. Refresh the URL if it expires.
  </Step>
</Steps>

## Response structure

When the request succeeds, the API returns a `recordings` array. Each item 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 [URL validity and refresh](#url-validity-and-refresh).
    </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>

## Example code

When the clinician opens Listen, call `GET https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/recording` with your Partner Token headers. Pass the `presigned_url` from the response to your player. The examples below request streaming URLs by default (`download` omitted). Add `?download=true` when you need the full WAV file.

<div className="doc-guide-btn-row">
  <a href="/api-reference/ambient-content/recording" className="doc-guide-btn">
    Get Ambient Session Recording API
  </a>
</div>

**Language tabs (agents):** Equivalent code samples are available in: TypeScript, Python. Humans see one language at a time. Use the variant that matches the user's stack; behavior is the same across tabs.

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const response = await fetch(
      `https://sdp.suki.ai/api/v1/ambient/session/${ambientSessionId}/recording`,
      {
        headers: {
          sdp_suki_token: sdpSukiToken,
          sdp_provider_id: sdpProviderId,
        },
      }
    );
    if (!response.ok) {
      throw new Error(`Get recording failed: ${response.status}`);
    }
    const data = await response.json();
    // data.recordings[].presigned_url, expires_at: use in your player
    for (const rec of data.recordings ?? []) {
      console.log(rec.presigned_url, rec.expires_at);
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import requests

    response = requests.get(
        f"https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/recording",
        headers={
            "sdp_suki_token": sdp_suki_token,
            "sdp_provider_id": sdp_provider_id,
        },
    )
    response.raise_for_status()
    data = response.json()
    for rec in data.get("recordings", []):
        print(rec.get("presigned_url"), rec.get("expires_at"))
    ```
  </Tab>
</Tabs>

## 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=true` when you need to store the file long-term within your compliance policy.
  * **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:** Request a new URL when `expires_at` has passed or playback fails.
  * **Use access responsibly:** All access is logged; ensure your use meets your compliance requirements.
</Tip>

## FAQs

<AccordionGroup>
  <Accordion title="What Is the Difference Between Streaming and Download" icon="waveform">
    | 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" icon="clock">
    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" icon="file">
    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" icon="layer-group">
    Yes. Some sessions return multiple recordings. Read the `recordings` array and use `sequence_number` to play or assemble chunks in order. If `is_streamable` is `false`, use `download=true` instead.
  </Accordion>

  <Accordion title="How Long Are Recordings Available" icon="calendar">
    Recordings are available for 7 days from the session date. After that, the recording is no longer accessible. Download within the 7-day window if you need long-term storage.
  </Accordion>

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

## Next steps

<Icon icon="file-lines" iconType="solid" /> **[Get Ambient session recording](/api-reference/ambient-content/recording)** - Request and response fields for presigned URLs.

<Icon icon="file-lines" iconType="solid" /> **[Load the note](/documentation/how-to/ambient-clinical-notes/retrieve-ambient-content)** - Retrieve note content and transcript without source audio.

<Icon icon="file-lines" iconType="solid" /> **[Complete an ambient visit](/documentation/how-to/ambient-clinical-notes/end-ambient-session)** - Finish capture before you fetch recording URLs.