Get Ambient Session Status

Check current status and processing state of Ambient session

GET /api/v1/ambient/session/{ambient_session_id}/status

cURL

cURL

curl --request GET \
  --url https://sdp.suki.ai/api/v1/ambient/session/<ambient_session_id>/status \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>'

200

{
  "status": "completed"
}

Use this endpoint to get the current status of an ambient session. Use it to track the session’s progress, for example, to see if it is ready to receive audio, still processing, or has completed.

Session status values

Use the following status values to track the session’s progress in your application UI:

• created: The ambient session has been created but has not yet started.

• ready: The ambient session has started and is ready for audio streaming.

• running: The ambient session is actively processing audio and generating content.

• aborted: The ambient session has been cancelled by the user or client.

• skipped: The ambient session was skipped because not enough audio was received or the transcript was empty.

• failed: The ambient session failed due to an error during processing.

• completed: The ambient session completed successfully and generated the final content.

paused status is no longer supported.

Upon reaching completed state, the session is ready to return the content, transcripts, or other structured data.

Poll status until you reach a terminal state (completed, skipped, failed, or aborted) before you call content or structured-data endpoints.

Code examples

Python

import requests

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

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

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

if response.status_code == 200:
    status_data = response.json()
    status = status_data.get("status")
    print(f"Session status: {status}")
    
    if status == "completed":
        print("Session completed successfully. Content is ready.")
    elif status == "failed":
        print("Session failed during processing.")
    elif status == "skipped":
        print("Session was skipped (empty transcript or too short).")
else:
    print(f"Failed to get status: {response.status_code}")
    print(response.json())

TypeScript

const ambientSessionId = '123dfg-456dfg-789dfg-012dfg';
const response = await fetch(
  `https://sdp.suki-stage.com/api/v1/ambient/session/${ambientSessionId}/status`,
  {
    headers: {
      'sdp_suki_token': '<sdp_suki_token>',
    'sdp_provider_id': '<sdp_provider_id>'
    }
  }
);

if (response.ok) {
  const statusData = await response.json();
  const status = statusData.status;
  console.log(`Session status: ${status}`);
  
  if (status === 'completed') {
    console.log('Session completed successfully. Content is ready.');
  } else if (status === 'failed') {
    console.log('Session failed during processing.');
  } else if (status === 'skipped') {
    console.log('Session was skipped (empty transcript or too short).');
  }
} else {
  const error = await response.json();
  console.error(`Failed to get status: ${response.status}`, error);
}

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

UUID for the ambient session. Use the ambient_session_id returned from Create Ambient Session, or the UUID you supplied in that request.

Response

200

application/json

Request succeeded.

Current processing status for an ambient session.

status · enum<string>

Processing state of the ambient session. Poll until the status is completed, failed, or aborted.

Available options: created, ready, running, paused, aborted, failed, completed

Example:

"completed"