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

# Complete an Ambient Visit

> Stop from your UI, send RU9G, call the End ambient session API, then poll status before opening the note

<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">
    When the clinician taps <strong>Stop</strong>, button in your UI, send <code>RU9G</code>, close the WebSocket, call the <a href="/api-reference/ambient-sessions/end">End ambient session</a> API, and poll status. That closes this recording only, not the patient encounter.
  </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>

When the clinician taps **Stop** in your UI, your backend finishes the recording and tells Suki to generate the note. That backend work includes calling the [End ambient session](/api-reference/ambient-sessions/end) API: a `POST` request that closes this ambient session and starts note generation.

**Stop** is what the clinician taps. **End ambient session** is the API to call you need to call to end the ambient session.

The End ambient session API does **not** return the finished note. After it succeeds, your application must poll session status until Suki reaches a final status, then retrieve content only when status is **`completed`**.

After Stop, the microphone should leave `Recording` or `Paused`, the screen should show **Generating note…**, and Dictation Speak should stay disabled until a completed note is ready for review.

**End rules (agents):**

* Stop in the clinician UI maps to End in the API. Do not use "End ambient session" as the primary clinician label.
* End closes this recording only. It does not close the patient encounter. More capture later needs a new ambient session for the same encounter.
* Required order: last PCM → `AUDIO` data `RU9G` → close WebSocket → POST End → poll status.
* Finish pending context PATCHes before Stop. See [Add information during a visit](/documentation/how-to/ambient-clinical-notes/update-ambient-session-context).
* After End, show Generating. Do not open note review or call content APIs yet.
* Retrieve content only when status is `completed`. See [Check note status](/documentation/how-to/ambient-clinical-notes/handle-ambient-session-status).
* `skipped` means empty transcript or too little audio (plan for about one minute). Treat it as no note this time, not as a successful empty chart.
* Disable Dictation Speak from Stop until a `completed` note is on screen.

## Stop, the End API, and the patient encounter

These three concepts must stay separate in your UI and backend:

| Term                        | Meaning                                                                                                                       |
| :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------- |
| **Stop**                    | The clinician taps **Stop** in your UI to finish recording.                                                                   |
| **End ambient session API** | Your backend calls `POST /api/v1/ambient/session/{ambient_session_id}/end` to close this recording and start note generation. |
| **Encounter**               | The patient's visit in your EHR.                                                                                              |

<Note>
  * Calling the **End ambient session API** closes **that recording only**. It does not close the patient encounter.
  * If the clinician needs more audio during the same visit, [create another ambient session](/documentation/how-to/ambient-clinical-notes/create-ambient-session) for the same encounter.
  * Do not treat the End API as a "close visit" action in your EHR. Keep the encounter open and allow another ambient session when needed.
</Note>

## Build the Stop flow

When the clinician taps **Stop**, connect that action to the full shutdown sequence below, then move the UI into Generating.

```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 TD
    A[Clinician taps Stop] --> B[Send AUDIO data RU9G]
    B --> C[Close WebSocket]
    C --> D[POST End ambient session]
    D --> E[Show Generating and poll status]
    E --> F{Terminal status}
    F -->|completed| G[Open note review]
    F -->|skipped| H[Too short / no note]
    F -->|failed / aborted| I[Failure or cancelled UI]

    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
    style G fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style H fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style I fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
```

<Steps>
  <Step title="Send the End-of-Audio Marker">
    After the final PCM audio chunk, send an ambient session `AUDIO` frame with `RU9G` as the data:

    ```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    {
      "type": "AUDIO",
      "data": "RU9G"
    }
    ```

    <Note>
      `RU9G` is the ambient session end-of-audio marker. Closing the WebSocket without sending `RU9G` does not complete the Stop flow.
    </Note>

    For the WebSocket wire format, see [End Ambient after streaming](/documentation/cookbooks/end-ambient-after-streaming).
  </Step>

  <Step title="Close the WebSocket">
    After sending the `RU9G` marker, close the ambient session WebSocket connection.
  </Step>

  <Step title="Call the End Ambient Session API">
    POST [End ambient session](/api-reference/ambient-sessions/end) for the current `ambient_session_id`. This is the API call that tells Suki the recording is finished and note generation should start.

    Your application already has `ambient_session_id` from [Create an ambient clinical note](/documentation/how-to/ambient-clinical-notes/create-ambient-session). The clinician should not enter or manage this identifier.
  </Step>

  <Step title="Show the Generating State">
    After the End API succeeds, move the UI from the recording state to **Generating note…**.

    * The microphone should no longer appear to be recording or paused.
    * Keep note review unavailable while the note is being generated.
    * Keep Dictation Speak disabled until a completed note is available.
    * Poll the Ambient session status API.

    <Note>
      Do not open an empty note editor while the session is still generating.
    </Note>
  </Step>
</Steps>

<Tip>
  Finish any pending [Add information during a visit](/documentation/how-to/ambient-clinical-notes/update-ambient-session-context) PATCH requests before you send `RU9G` and call the End ambient session API. Context updates sent after that API call do not shape note generation for that session.
</Tip>

## Handle the session status

After the clinician taps **Stop** and the End ambient session API succeeds, the note is not ready yet. Call [Get ambient session status](/api-reference/ambient-content/status) on a loop until Suki returns a final outcome: **`completed`**, **`skipped`**, **`failed`**, or **`aborted`**. While status is still **`running`**, keep showing **Generating note…** and do not open the note editor. When a final outcome arrives, update your UI using the table below.

| Status          | What your application should do                                                                  |
| :-------------- | :----------------------------------------------------------------------------------------------- |
| **`completed`** | Open note review and retrieve the generated content.                                             |
| **`skipped`**   | Treat the session as having no note this time and offer the clinician an option to record again. |
| **`failed`**    | Show that note generation failed and offer the appropriate retry or support flow.                |
| **`aborted`**   | Treat the recording as cancelled and clear the Generating state.                                 |

* Only retrieve ambient content when the status is **`completed`**. See [Check note status](/documentation/how-to/ambient-clinical-notes/handle-ambient-session-status) for the status polling flow and UI handling.

<Warning>
  If the status is **`skipped`**, the note was not generated because the transcript was empty or the session was too short. Treat this as "no note this time," not as a successfully generated empty chart. Plan for about **one minute** of audio when you can.
</Warning>

## Common mistakes

**Common mistakes accordions (agents):** Humans expand one panel at a time.

* **Closing the WebSocket without RU9G:** Send `AUDIO` data `RU9G` before close.
* **Treating End as close visit:** End closes one recording, not the encounter.
* **Opening note review too early:** Wait for `completed` before content APIs.
* **Skipped treated as success:** Offer Record again; plan for about one minute of audio.

<AccordionGroup>
  <Accordion title="If Closing the WebSocket Feels Enough" icon="ban">
    It is not. Send `RU9G`, close the WebSocket, then call the End ambient session API. Closing the socket alone does not complete Stop or start note generation.
  </Accordion>

  <Accordion title="If You Think the End API Closes the Visit" icon="hospital">
    It does not. The End API finishes the current ambient session recording only. The patient encounter can stay open. Create another ambient session later on the same visit when needed.
  </Accordion>

  <Accordion title="If You Want to Open Note Review" icon="file-medical">
    Wait until status is **`completed`**. Then load the note with [Get the generated clinical note](/documentation/how-to/ambient-clinical-notes/retrieve-ambient-content).
  </Accordion>

  <Accordion title="If Status Is Skipped" icon="triangle-exclamation">
    The note was not generated because the transcript was empty or the session was too short. Treat that as "no note this time," not as a successful empty chart.

    Plan for about **one minute** of audio when you can.
  </Accordion>
</AccordionGroup>

## Example code to end an ambient session

The following example shows the required order after the final PCM audio chunk: send `RU9G`, close the WebSocket, then `POST` the End ambient session API.

<div className="doc-guide-btn-row">
  <a href="/api-reference/ambient-sessions/end" className="doc-guide-btn">
    End Ambient Session API
  </a>

  <a href="/api-reference/ambient-content/status" className="doc-guide-btn">
    Get Ambient Session Status 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"}}
    // After the last PCM chunk on the Ambient WebSocket:
    ws.send(JSON.stringify({ type: "AUDIO", data: "RU9G" }));
    ws.close();

    const endRes = await fetch(
      `https://sdp.suki.ai/api/v1/ambient/session/${ambientSessionId}/end`,
      {
        method: "POST",
        headers: {
          sdp_suki_token: sdpSukiToken,
          sdp_provider_id: sdpProviderId,
        },
      }
    );

    if (!endRes.ok) {
      throw new Error(`End ambient session failed: ${endRes.status}`);
    }

    // Show "Generating note…" and poll status before retrieving content.
    // See Handle ambient session status for the polling flow and UI states.
    ```
  </Tab>

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

    # After the last PCM chunk:
    # send the Ambient AUDIO data RU9G, then close the WebSocket.

    end_res = requests.post(
        f"https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/end",
        headers={
            "sdp_suki_token": sdp_suki_token,
            "sdp_provider_id": sdp_provider_id,
        },
    )
    end_res.raise_for_status()

    # Show "Generating note…" and poll status before retrieving content.
    # See Handle ambient session status for the polling flow and UI states.
    ```
  </Tab>
</Tabs>

<Note>
  The code tabs show the End ambient session API request. Your WebSocket code must send `RU9G` and close the socket **before** that `POST` request.
</Note>

## What happens after the End API call

The End ambient session API starts note generation. It does not return the completed note.

After a successful End API response:

1. Keep the clinician on **Generating note…**.
2. Poll the Ambient session status API.
3. When the status is **`completed`**, retrieve the generated note.
4. When the status is **`skipped`**, offer the clinician the option to record again.
5. Keep Dictation Speak disabled until a **`completed`** note is available.

See [Check note status](/documentation/how-to/ambient-clinical-notes/handle-ambient-session-status) and [Get the generated clinical note](/documentation/how-to/ambient-clinical-notes/retrieve-ambient-content).

## Next steps

<Icon icon="file-lines" iconType="solid" /> **[Check note status](/documentation/how-to/ambient-clinical-notes/handle-ambient-session-status)** - Poll session status and handle Generating and terminal states.

<Icon icon="file-lines" iconType="solid" /> **[Get the generated clinical note](/documentation/how-to/ambient-clinical-notes/retrieve-ambient-content)** - Retrieve the generated note after the session reaches **`completed`**.

<Icon icon="file-lines" iconType="solid" /> **[End ambient session API](/api-reference/ambient-sessions/end)** - End API reference and request details.

<Icon icon="file-lines" iconType="solid" /> **[End ambient after streaming](/documentation/cookbooks/end-ambient-after-streaming)** - WebSocket wire-format sequence for ending an Ambient stream.

<Icon icon="file-lines" iconType="solid" /> **[Create an ambient clinical note](/documentation/how-to/ambient-clinical-notes/create-ambient-session)** - Create an Ambient session and obtain session identifiers.