> ## 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 Form Filling Session Status

> Poll processing status for a Form filling session

Use this endpoint to know the processing status for a Form filling session. Use your ambient session identifier (id) to identify the session you want to check the status of.

## Form filling session status values

Use the following status values to track session progress:

* **created**: The system creates the Form filling session but does not start it yet.

* **ready**: The Form filling session starts and is ready for audio streaming.

* **running**: The Form filling session processes audio and generates content.

* **staged**: The Form filling session is staged and is ready to be processed.

* **aborted**: The user or client cancels the Form filling session.

* **failed**: An error stops the Form filling session during processing.

* **completed**: The Form filling session completes successfully and generates the final content.

## Code examples

<Note>
  The code examples below use placeholders and the stage host `sdp.suki-stage.com` only as **examples**.
  For credentials, base URLs, where to run Python or TypeScript, CORS, and **cURL**, refer to [Using code examples in your integration](/api-reference/api-guidelines#using-code-examples-in-your-integration) in the **API Reference Guidelines**.
</Note>

**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 expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    from typing import Any, Literal, TypedDict

    import requests

    BASE_URL = "https://sdp.suki-stage.com"

    StatusValue = Literal[
        "created",
        "ready",
        "running",
        "paused",
        "aborted",
        "failed",
        "completed",
        "staged",
    ]


    class StatusResponse(TypedDict):
        status: StatusValue


    class ApiHttpError(RuntimeError):
        """Wrong HTTP status; OpenAPI errors usually include JSON with message + code."""

        def __init__(self, status: int, url: str, detail: str) -> None:
            super().__init__(f"HTTP {status} {url}: {detail}")
            self.status = status
            self.url = url


    def _get_expect_json_object(url: str, headers: dict[str, str], expect_status: int) -> dict[str, Any]:
        r = requests.get(url, headers=headers, timeout=60)
        if r.status_code == expect_status:
            data = r.json()
            if isinstance(data, dict):
                return data
            raise ApiHttpError(expect_status, url, "response JSON was not an object")

        detail = ""
        try:
            err = r.json()
            if isinstance(err, dict) and isinstance(err.get("message"), str):
                detail = err["message"]
        except ValueError:
            detail = (r.text or "")[:500]
        raise ApiHttpError(r.status_code, url, detail or "(no body)")


    def get_form_filling_session_status(suki_token: str, ambient_session_id: str) -> StatusResponse:
        """GET /api/v1/form-filling/session/{ambient_session_id}/status (sdp_suki_token header required). HTTP 200."""
        url = f"{BASE_URL}/api/v1/form-filling/session/{ambient_session_id}/status"
        data = _get_expect_json_object(url, {"sdp_suki_token": suki_token, "sdp_provider_id": "<sdp_provider_id>"}, 200)
        status = data.get("status")
        if not isinstance(status, str) or not status:
            raise ValueError(f"{url}: 200 response missing status")
        return {"status": status}  # type: ignore[return-value]


    if __name__ == "__main__":
        try:
            out = get_form_filling_session_status("YOUR_SUKI_TOKEN", "YOUR_AMBIENT_SESSION_ID")
            print(out["status"])
        except (ApiHttpError, ValueError) as e:
            print(e)
    ```
  </Tab>

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

    type StatusValue =
      | "created"
      | "ready"
      | "running"
      | "paused"
      | "aborted"
      | "failed"
      | "completed";

    type StatusResponse = { status: StatusValue };

    class ApiHttpError extends Error {
      status: number;
      url: string;
      constructor(status: number, url: string, detail: string) {
        super(`HTTP ${status} ${url}: ${detail}`);
        this.status = status;
        this.url = url;
      }
    }

    async function getExpectJsonObject(url: string, headers: Record<string, string>, expectStatus: number) {
      const res = await fetch(url, { method: "GET", headers });
      const text = await res.text();
      const json = text ? JSON.parse(text) : {};

      if (res.status !== expectStatus) {
        const msg = typeof (json as any)?.message === "string" ? (json as any).message : text?.slice(0, 500) || "(no body)";
        throw new ApiHttpError(res.status, url, msg);
      }
      if (json && typeof json === "object" && !Array.isArray(json)) return json as Record<string, unknown>;
      throw new ApiHttpError(res.status, url, "response JSON was not an object");
    }

    export async function getFormFillingSessionStatus(sukiToken: string, ambientSessionId: string): Promise<StatusResponse> {
      const url = `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/status`;
      const data = await getExpectJsonObject(url, { sdp_suki_token: sukiToken, sdp_provider_id: "<sdp_provider_id>" }, 200);
      const status = data.status;
      if (typeof status !== "string" || !status) {
        throw new Error(`${url}: 200 response missing status`);
      }
      return { status: status as StatusValue };
    }

    // Example usage
    const out = await getFormFillingSessionStatus("YOUR_SUKI_TOKEN", "YOUR_AMBIENT_SESSION_ID");
    console.log(out.status);
    ```
  </Tab>
</Tabs>


## OpenAPI

````yaml GET /api/v1/form-filling/session/{ambient_session_id}/status
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/form-filling/session/{ambient_session_id}/status:
    get:
      tags:
        - /api/v1/form-filling/session
      summary: Get form-filling session status
      description: Returns processing status for a form-filling session.
      parameters:
        - name: ambient_session_id
          in: path
          description: >-
            Form-filling session ID. The path parameter is named
            `ambient_session_id`, but this value identifies the form-filling
            session, not an ambient clinical documentation session. Use the ID
            returned from Create Form filling 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.FormFillingStatusResponse'
        '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/form-filling/session/<ambient_session_id>/status \
              --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.FormFillingStatusResponse:
      type: object
      description: Current processing status for a form-filling session.
      properties:
        status:
          type: string
          description: >-
            Processing state of the form-filling session. Poll until the status
            is `completed`, `failed`, or `aborted`.
          example: completed
          enum:
            - created
            - ready
            - running
            - paused
            - aborted
            - failed
            - completed
    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
  securitySchemes:
    SukiTokenAuth:
      type: apiKey
      in: header
      name: sdp_suki_token
      description: >-
        Suki access token (`suki_token`) from Login or Register. Expires after
        one hour.

````