Get Form Filling Session Status

GET

api

form-filling

session

{ambient_session_id}

status

cURL

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>'

import requests

url = "https://sdp.suki.ai/api/v1/form-filling/session/{ambient_session_id}/status"

headers = {"sdp_suki_token": "<api-key>"}

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

print(response.text)

const options = {method: 'GET', headers: {sdp_suki_token: '<api-key>'}};

fetch('https://sdp.suki.ai/api/v1/form-filling/session/{ambient_session_id}/status', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sdp.suki.ai/api/v1/form-filling/session/{ambient_session_id}/status",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "sdp_suki_token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://sdp.suki.ai/api/v1/form-filling/session/{ambient_session_id}/status"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("sdp_suki_token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://sdp.suki.ai/api/v1/form-filling/session/{ambient_session_id}/status")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["sdp_suki_token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "status": "completed"
}

{
  "code": 400,
  "message": "invalid request"
}

{
  "code": 401,
  "message": "invalid token"
}

{
  "code": 404,
  "message": "not found"
}

{
  "code": 500,
  "message": "internal server error"
}

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

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 in the API Reference Guidelines.

Python
TypeScript

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)

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);

Authorizations

sdp_suki_token

string

header

required

Suki access token (suki_token) from Login or Register. Expires after one hour.

Headers

sdp_provider_id

string

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.

Example:

"provider-123"

Path Parameters

ambient_session_id

string

required

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.

Response

Request succeeded.

Current processing status for a form-filling session.

status

enum<string>

Processing state of the form-filling session. Poll until the status is completed, failed, or aborted.

Available options:

created,

ready,

running,

paused,

aborted,

failed,

completed

Example:

"completed"

Last modified on August 13, 2026

cURL

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>'

import requests

url = "https://sdp.suki.ai/api/v1/form-filling/session/{ambient_session_id}/status"

headers = {"sdp_suki_token": "<api-key>"}

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

print(response.text)

const options = {method: 'GET', headers: {sdp_suki_token: '<api-key>'}};

fetch('https://sdp.suki.ai/api/v1/form-filling/session/{ambient_session_id}/status', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sdp.suki.ai/api/v1/form-filling/session/{ambient_session_id}/status",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "sdp_suki_token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://sdp.suki.ai/api/v1/form-filling/session/{ambient_session_id}/status"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("sdp_suki_token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://sdp.suki.ai/api/v1/form-filling/session/{ambient_session_id}/status")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["sdp_suki_token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "status": "completed"
}

{
  "code": 400,
  "message": "invalid request"
}

{
  "code": 401,
  "message": "invalid token"
}

{
  "code": 404,
  "message": "not found"
}

{
  "code": 500,
  "message": "internal server error"
}

Get Started

API References

Get Form Filling Session Status

Form filling session status values

Code examples

Authorizations

Headers

Path Parameters

Response

​Form filling session status values

​Code examples

Authorizations

Headers

Path Parameters

Response

Form filling session status values

Code examples