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

# Get Ambient Session Content

> Retrieve generated clinical content from completed Ambient session

<Callout title="Updates" color="orange" icon="bell">
  **Updated:**

  You can now get the structured data blocks in the response of this API, including medication orders details.
</Callout>

Use this endpoint to get the summary 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> associated with the specified <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 session</Tooltip>.

This endpoint uses the `cumulative` query parameter to get the cumulative summary and structured data for the specified ambient session. If the query parameter is not provided, the default value is `false`.

You have two options for the `cumulative` query parameter:

<ResponseField name="cumulative" type="boolean">
  Determines whether to retrieve cumulative or snapshot data.

  <Expandable title="Options">
    <ResponseField name="true" type="boolean">
      Cumulative summary and structured data up to the specified ambient session is retrieved.
    </ResponseField>

    <ResponseField name="false" type="boolean">
      Snapshot summary and structured data for the specified ambient session is retrieved.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  **Understanding the SKIPPED Status**

  If you see a session with a `SKIPPED` status, it means that the <Tooltip tip="The structured medical documentation produced for a patient encounter. In Suki, ambient note generation organizes content into LOINC-coded sections so partners can review, edit, and submit notes into an EHR-ready workflow." cta="View in Glossary" href="/Glossary/c">clinical note</Tooltip> was **not generated** because the conversation <Tooltip tip="The text version of recorded audio from clinical conversations, generated by automatic speech recognition." cta="View in Glossary" href="/Glossary/t">transcript</Tooltip> was **empty**.

  This status is an expected outcome if an ambient session is started but contains no audible speech (for example, a silent recording). It does not indicate a system error.

  Unlike a `FAILED` status, which indicates a processing error, `SKIPPED` is a successful outcome where no action was needed. Typically filter out or ignore sessions with this status in your application's user interface.
</Note>

## Code examples

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

    ambient_session_id = "123dfg-456dfg-789dfg-012dfg"
    url = f"https://sdp.suki-stage.com/api/v1/ambient/session/{ambient_session_id}/content"

    headers = {
        "sdp_suki_token": "<sdp_suki_token>",
        "sdp_provider_id": "<sdp_provider_id>"
    }

    # Get snapshot content (default, cumulative=false)
    response = requests.get(url, headers=headers, params={"cumulative": False})

    if response.status_code == 200:
        content = response.json()
        print("Structured data blocks:")
        for block in content.get("structured_data", []) or []:
            print(f"\nBlock title: {block.get('title')}")
            data = block.get("data") or {}
            for key, value in data.items():
                print(f"  {key}: {value}")

        print("\nGenerated note (summary):")
        for section in content.get("summary", []) or []:
            print(f"\nTitle: {section.get('title')}")
            print(f"LOINC Code: {section.get('loinc_code')}")
            print(f"Content: {section.get('content')}")
    else:
        print(f"Failed to get content: {response.status_code}")
        print(response.json())
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const ambientSessionId = '123dfg-456dfg-789dfg-012dfg';

    // Get snapshot content (default, cumulative=false)
    const response = await fetch(
      `https://sdp.suki-stage.com/api/v1/ambient/session/${ambientSessionId}/content?cumulative=false`,
      {
        headers: {
          'sdp_suki_token': '<sdp_suki_token>',
        'sdp_provider_id': '<sdp_provider_id>'
        }
      }
    );

    if (response.ok) {
        const content = await response.json();
        console.log('Structured data blocks:');
        (content.structured_data || []).forEach((block: any) => {
            console.log(`\nBlock title: ${block.title}`);
            const data = block.data || {};
            Object.entries(data).forEach(([key, value]) => {
                console.log(`  ${key}: ${value}`);
            });
        });

        console.log('\nGenerated note (summary):');
        content.summary?.forEach((section: any) => {
            console.log(`\nTitle: ${section.title}`);
            console.log(`LOINC Code: ${section.loinc_code}`);
            console.log(`Content: ${section.content}`);
        });
    } else {
      const error = await response.json();
      console.error(`Failed to get content: ${response.status}`, error);
    }
    ```
  </Tab>
</Tabs>


## OpenAPI

````yaml GET /api/v1/ambient/session/{ambient_session_id}/content
openapi: 3.0.1
info:
  title: Suki Developer Platform
  description: >-
    REST and WebSocket APIs for the Suki Developer Platform. Authenticate with
    Login or Register to obtain a Suki access token, then integrate ambient
    clinical documentation, form filling, transcription, and reference metadata
    endpoints.
  contact: {}
  version: '1.0'
servers:
  - url: https://sdp.suki.ai
    description: >-
      Production base URL for Suki Developer Platform REST APIs. WebSocket
      endpoints use the same host with `wss://`.
security:
  - SukiTokenAuth: []
paths:
  /api/v1/ambient/session/{ambient_session_id}/content:
    get:
      tags:
        - /api/v1/ambient/session
      summary: Get ambient session content
      description: >-
        Returns the generated clinical note and related content for a completed
        or in-progress ambient session. Poll session status if content is not
        ready yet.
      parameters:
        - name: ambient_session_id
          in: path
          description: >-
            UUID for the ambient session. Use the `ambient_session_id` returned
            from Create Ambient Session, or the UUID you supplied in that
            request.
          required: true
          schema:
            type: string
        - name: cumulative
          in: query
          description: >-
            Optional. When `true`, return cumulative summary and structured data
            up to this session. When `false` (default), return snapshot data for
            this session only.
          schema:
            type: boolean
            default: false
        - $ref: '#/components/parameters/ProviderIdHeader'
      responses:
        '200':
          description: Request succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.SessionContentResponse'
              example:
                structured_data:
                  - title: MEDICATIONS
                    data:
                      medication: albuterol
                      dosage: 2 puffs
                summary:
                  - content: Asthma exacerbation
                    loinc_code: 18776-5
                    title: ASSESSMENT AND PLAN
        '400':
          description: Bad request. The request body or parameters failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.BadRequestError'
        '401':
          description: Unauthorized. The Suki access token is missing, expired, or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.AuthenticationError'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.InternalServerError'
      security:
        - SukiTokenAuth: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --request GET \
              --url https://sdp.suki.ai/api/v1/ambient/session/<ambient_session_id>/content?cumulative=<cumulative> \
              --header 'sdp_suki_token: <sdp_suki_token>' \
              --header 'sdp_provider_id: <sdp_provider_id>'
components:
  parameters:
    ProviderIdHeader:
      name: sdp_provider_id
      in: header
      description: >-
        **Optional** for standard partners.


        **Required** for:


        - **Bearer authentication.** Use the same `provider_id` returned by the
        Login or Register API.

        - **Single Auth Token authentication.** Include the same `provider_id`
        on every request as `sdp_provider_id`.
      required: false
      schema:
        type: string
        example: provider-123
  schemas:
    controllers.SessionContentResponse:
      type: object
      properties:
        structured_data:
          type: array
          description: Structured data extracted from the ambient session.
          items:
            $ref: '#/components/schemas/controllers.StructuredDataBlock'
        summary:
          type: array
          description: Summary of the ambient session.
          items:
            $ref: '#/components/schemas/controllers.ContentBlock'
      description: Response body for the /session/{ambient_session_id}/content endpoint
    controllers.BadRequestError:
      description: Bad Request Response
      type: object
      properties:
        code:
          type: integer
          example: 400
        message:
          type: string
          example: invalid request
    controllers.AuthenticationError:
      description: Authentication Failure Response
      type: object
      properties:
        code:
          type: integer
          example: 401
        message:
          type: string
          example: invalid token
    controllers.InternalServerError:
      description: Internal Server Error Response
      type: object
      properties:
        code:
          type: integer
          example: 500
        message:
          type: string
          example: internal server error
    controllers.StructuredDataBlock:
      type: object
      properties:
        data:
          type: object
          additionalProperties:
            type: string
          description: >-
            The structured data in the block. This is a key-value pair where the
            key is the name of the data and the value is the data itself.

            For example, for medications, the key can be the name of the
            medication and the value can be the dosage.

            This is kept as map since we don't know the structure of the data
            that will be extracted.
          example:
            dosage: 2 puffs
            medication: albuterol
        title:
          type: string
          description: >-
            The title of the structured data block. Usually refers to names like
            Medications, Allergies, etc.
          example: MEDICATIONS
    controllers.ContentBlock:
      type: object
      properties:
        content:
          description: >-
            The body of the content block usually refers to the content of the
            section.
          type: string
          example: Asthma exacerbation
        loinc_code:
          description: The LOINC code of the content block.
          type: string
          example: 18776-5
        source_transcripts:
          description: The source transcripts that were used to generate the content block.
          type: array
          items:
            type: string
          example:
            - asthma
            - exacerbation
        title:
          description: The title of the content block usually refers to section name.
          type: string
          example: ASSESSMENT AND PLAN
  securitySchemes:
    SukiTokenAuth:
      type: apiKey
      in: header
      name: sdp_suki_token
      description: >-
        Suki access token (`suki_token`) from Login or Register. Expires after
        one hour.

````