> ## 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 Section Structured Data

> Retrieve filled Embedded Form values for a completed ambient session

Use this endpoint to retrieve filled [Embedded Form](/documentation/concepts/ambient-clinical-notes/embedded-forms) values for a specific <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>.

Call this endpoint once [Session status](/api-reference/ambient-content/status) reaches `completed` state, or you receive a `_links.section_structured_data` link from the ambient SUCCESS webhook. To retrieve values from the latest completed ambient session for an encounter, use the [Encounter Section Structured Data endpoint](/api-reference/ambient-content/encounter-section-structured-data) instead.

<Note>
  For how to seed templates, read the response, and map values back to your form, refer to [Seed and read Embedded Forms](/documentation/how-to/ambient-clinical-notes/seed-and-read-embedded-forms#read-the-filled-values).
</Note>

## Code examples

**Language tabs (agents):** Equivalent code samples are available in: Python, TypeScript. 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="Python">
    ```python theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
    import requests

    ambient_session_id = "<ambient_session_id>"
    url = f"https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/structured-data/section-structured-data"

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

    response = requests.get(url, headers=headers)

    if response.status_code == 200:
        sections = response.json().get("section_structured_values") or []
        if not sections:
            print("No Embedded Form values for this session.")
        for section in sections:
            print(f"Section {section.get('loinc_code')}")
            for form in section.get("forms") or []:
                print(f"  Template {form.get('template_id')}")
                for field in form.get("values") or []:
                    # value is a string, a list of strings, or None
                    print(f"    {field.get('key')} ({field.get('id')}): {field.get('value')}")
    else:
        print(f"Failed to get section structured data: {response.status_code}")
        print(response.json())
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
    type FilledValue = { id?: string; key: string; value?: string | string[] | null };
    type SectionStructuredData = {
      loinc_code?: string;
      forms?: Array<{ template_id?: string; values?: FilledValue[] }>;
    };

    const ambientSessionId = "<ambient_session_id>";
    const response = await fetch(
      `https://sdp.suki.ai/api/v1/ambient/session/${ambientSessionId}/structured-data/section-structured-data`,
      {
        headers: {
          sdp_suki_token: "<sdp_suki_token>",
          sdp_provider_id: "<sdp_provider_id>",
        },
      }
    );

    if (response.ok) {
      const body: { section_structured_values?: SectionStructuredData[] } = await response.json();
      const sections = body.section_structured_values ?? [];
      if (sections.length === 0) {
        console.log("No Embedded Form values for this session.");
      }
      sections.forEach((section) => {
        console.log(`Section ${section.loinc_code}`);
        section.forms?.forEach((form) => {
          console.log(`  Template ${form.template_id}`);
          form.values?.forEach((field) => {
            // value is a string, a list of strings, or null
            console.log(`    ${field.key} (${field.id}): ${JSON.stringify(field.value ?? null)}`);
          });
        });
      });
    } else {
      const error = await response.json();
      console.error(`Failed to get section structured data: ${response.status}`, error);
    }
    ```
  </Tab>
</Tabs>


## OpenAPI

````yaml GET /api/v1/ambient/session/{ambient_session_id}/structured-data/section-structured-data
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, content rewrite, 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}/structured-data/section-structured-data:
    get:
      tags:
        - /api/v1/ambient/session
      summary: Get session section structured data
      description: >-
        Returns Embedded Form results for the ambient session, grouped by
        section LOINC. Call it after the session status is `completed`. Use [Get
        ambient session structured
        data](/api-reference/ambient-content/structured-data) when you also need
        diagnoses and orders.
      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
        - $ref: '#/components/parameters/ProviderIdHeader'
      responses:
        '200':
          description: Request succeeded.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/controllers.SessionSectionStructuredDataResponse
              example:
                section_structured_values:
                  - loinc_code: 10164-2
                    forms:
                      - template_id: hpi-mood-v1
                        values:
                          - id: slot-symptoms
                            key: symptoms
                            value:
                              - low mood
                              - poor sleep
                          - id: slot-duration
                            key: symptom_duration
                            value: in the last two weeks
                          - id: slot-onset
                            key: onset_date
                            value: null
        '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'
        '404':
          description: Not found. The session, encounter, or resource ID does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.NotFoundError'
        '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>/structured-data/section-structured-data \
              --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.SessionSectionStructuredDataResponse:
      type: object
      description: >-
        Response body for the
        /session/{ambient_session_id}/structured-data/section-structured-data
        endpoint
      properties:
        section_structured_values:
          type: array
          description: >-
            Embedded Form results for the ambient session, grouped by section
            LOINC.
          items:
            $ref: '#/components/schemas/controllers.SectionStructuredData'
    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.NotFoundError:
      description: Not Found Response
      type: object
      properties:
        code:
          type: integer
          example: 404
        message:
          type: string
          example: not found
    controllers.InternalServerError:
      description: Internal Server Error Response
      type: object
      properties:
        code:
          type: integer
          example: 500
        message:
          type: string
          example: internal server error
    controllers.SectionStructuredData:
      type: object
      description: Embedded Form results for one note section.
      properties:
        loinc_code:
          type: string
          description: LOINC code of the note section you seeded.
          example: 10164-2
        forms:
          type: array
          description: One entry for each Embedded Form template filled on this section.
          items:
            $ref: '#/components/schemas/controllers.SectionStructuredDataForm'
    controllers.SectionStructuredDataForm:
      type: object
      description: Filled values for one Embedded Form template.
      properties:
        template_id:
          type: string
          description: The `template_id` you sent on the seed request.
          example: hpi-mood-v1
        values:
          type: array
          description: Filled values for the template fields.
          items:
            $ref: '#/components/schemas/controllers.SectionStructuredDataValue'
    controllers.SectionStructuredDataValue:
      type: object
      description: >-
        One filled field. Returns `id`, `key`, and `value` only. The seed
        `type`, `options`, and `context` are not returned.
      properties:
        id:
          type: string
          description: The field `id` you sent, if any.
          example: slot-duration
        key:
          type: string
          description: The field `key` you sent.
          example: symptom_duration
        value:
          description: >-
            The filled value. A string for `text` and `radio`, a list of strings
            for `multi_select`, or `null` when the visit did not support a
            value.
          example: in the last two weeks
  securitySchemes:
    SukiTokenAuth:
      type: apiKey
      in: header
      name: sdp_suki_token
      description: >-
        Suki access token (`suki_token`) from Login or Register. Expires after
        one hour.

````

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