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

# List Encounter Notes

> List Ambient notes linked to an EMR encounter for cross-modality workflows

Use this endpoint to list all notes (compositions) tied to an <Tooltip tip="The partner EMR or EHR visit identifier (emr_encounter_id) that anchors interoperable ambient notes across modalities. Required for cross-modality ambient workflows. Must be a UUID today. Distinct from the Ambient API encounter_id session group field." cta="View in Glossary" href="/Glossary/e#emr-encounter-id">EMR Encounter ID</Tooltip>.

Pass the same `emr_encounter_id` you sent when creating interoperable ambient sessions. Use each returned note `id` as <Tooltip tip="Unique identifier for an interoperable ambient note. Create ambient session returns composition_id; pass that value as note_id to note-level ambient endpoints such as note content, note context, and note structured data." cta="View in Glossary" href="/Glossary/n#note-id-ambient-apis">`note_id`</Tooltip> with the note-level content, context, and structured data endpoints.

<Note>
  Cross-modality ambient workflows require `emr_encounter_id` on session create. Without it, notes are not interoperable across modalities. See [Ambient interoperability](/documentation/concepts/ambient-clinical-notes/ambient-interoperability) for more details.
</Note>

## Code examples

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

    BASE_URL = "https://sdp.suki.ai"

    # Same emr_encounter_id you passed on Create Ambient Session
    emr_encounter_id = "<emr_encounter_id>"

    # Get sdp_suki_token from Login: POST /api/v1/auth/login
    sdp_suki_token = "<sdp_suki_token>"

    # Required for single_auth partners
    sdp_provider_id = "<sdp_provider_id>"

    url = f"{BASE_URL}/api/v1/ambient/encounter/{emr_encounter_id}/notes"

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

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

    print("HTTP status:", response.status_code)

    try:
        response_body = response.json()
    except ValueError:
        print("Response was not JSON:")
        print(response.text)
        raise SystemExit(1)

    print("Response body:")
    print(json.dumps(response_body, indent=2))

    if response.status_code == 200:
        notes = response_body.get("notes") or []
        print(f"Notes found: {len(notes)}")

        for note in notes:
            note_id = note.get("id")
            status = note.get("status")
            created_at = note.get("created_at")
            updated_at = note.get("updated_at")

            print("note_id:", note_id)
            print("status:", status)
            print("created_at:", created_at)
            print("updated_at:", updated_at)
            print(
                "Use note_id with Get Note Content, Get Note Context, "
                "and Get Note Structured Data."
            )
    else:
        print("List Encounter Notes failed.")
        if isinstance(response_body, dict):
            print("code:", response_body.get("code"))
            print("message:", response_body.get("message"))
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const BASE_URL = "https://sdp.suki.ai";

    // Same emr_encounter_id you passed on Create Ambient Session
    const emrEncounterId = "<emr_encounter_id>";

    // Get sdp_suki_token from Login: POST /api/v1/auth/login
    const sdpSukiToken = "<sdp_suki_token>";

    // Required for single_auth partners
    const sdpProviderId = "<sdp_provider_id>";

    type EncounterNote = {
      id?: string;
      status?: string;
      created_at?: string;
      updated_at?: string;
    };

    type ListEncounterNotesResponse = {
      notes?: EncounterNote[];
    };

    type ApiErrorResponse = {
      code?: number;
      message?: string;
    };

    const response = await fetch(
      `${BASE_URL}/api/v1/ambient/encounter/${emrEncounterId}/notes`,
      {
        method: "GET",
        headers: {
          sdp_suki_token: sdpSukiToken,
          sdp_provider_id: sdpProviderId,
        },
      }
    );

    const responseText = await response.text();
    let responseBody: ListEncounterNotesResponse | ApiErrorResponse | unknown;

    try {
      responseBody = responseText ? JSON.parse(responseText) : {};
    } catch {
      console.error("Response was not JSON:");
      console.error(responseText);
      throw new Error("List Encounter Notes returned non-JSON response");
    }

    console.log("HTTP status:", response.status);
    console.log("Response body:", JSON.stringify(responseBody, null, 2));

    if (response.status === 200) {
      const payload = responseBody as ListEncounterNotesResponse;
      const notes = payload.notes || [];
      console.log(`Notes found: ${notes.length}`);

      for (const note of notes) {
        console.log("note_id:", note.id);
        console.log("status:", note.status);
        console.log("created_at:", note.created_at);
        console.log("updated_at:", note.updated_at);
        console.log(
          "Use note_id with Get Note Content, Get Note Context, and Get Note Structured Data."
        );
      }
    } else {
      const error = responseBody as ApiErrorResponse;
      console.error("List Encounter Notes failed.");
      console.error("code:", error.code);
      console.error("message:", error.message);
    }
    ```
  </Tab>
</Tabs>


## OpenAPI

````yaml GET /api/v1/ambient/encounter/{emr_encounter_id}/notes
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/encounter/{emr_encounter_id}/notes:
    get:
      tags:
        - /api/v1/ambient/encounter
      summary: Lists notes for an EMR encounter.
      parameters:
        - $ref: '#/components/parameters/ProviderIdHeader'
        - name: emr_encounter_id
          in: path
          required: true
          description: >-
            UUID for the EMR encounter. Same value you pass as
            `emr_encounter_id` on Ambient session create for interoperable
            workflows.
          schema:
            type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ListEncounterNotesResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.AuthenticationError'
        '404':
          description: Not Found
          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: []
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.ListEncounterNotesResponse:
      description: Notes linked to the EMR encounter.
      type: object
      properties:
        notes:
          description: All notes (compositions) for the EMR encounter.
          type: array
          items:
            $ref: '#/components/schemas/controllers.EncounterNote'
    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.EncounterNote:
      description: A single note (composition) for an EMR encounter.
      type: object
      properties:
        created_at:
          description: Note creation time (RFC3339).
          type: string
          example: '2026-01-01T00:00:00Z'
        id:
          type: string
          example: 123dfg-456dfg-789dfg-012dfg
        status:
          description: 'Note status. Example value returned by the API: INCOMPLETE.'
          type: string
          example: INCOMPLETE
        updated_at:
          description: Note last-update time (RFC3339); unset for signed NOTEs (immutable).
          type: string
          example: '2026-01-01T00:00:00Z'
  securitySchemes:
    SukiTokenAuth:
      type: apiKey
      in: header
      name: sdp_suki_token
      description: >-
        Suki access token (`suki_token`) from Login or Register. Expires after
        one hour.

````