Polling Session Status

Polling allows you to monitor session progress and retrieve results by periodically checking the session status. This is an alternative to webhooks that’s useful when you can’t receive incoming HTTP requests or prefer a pull-based approach.

Usage

TypeScript
Python

import { SimplexClient, SessionStatusResponse } from 'simplex-ts';

const client = new SimplexClient({
  apiKey: process.env.SIMPLEX_API_KEY!
});

// Start a workflow
const result = await client.workflows.run(workflowId, {
  variables: { patient_id: 'P-12345', insurance_provider: 'Blue Cross' }
});

const sessionId = result.session_id;

// Poll until complete
let status: SessionStatusResponse;
do {
  status = await client.getSessionStatus(sessionId);

  if (status.paused) {
    console.log('Session paused, waiting for resume...');
  } else if (status.in_progress) {
    console.log('Session still running...');
  }

  if (status.in_progress) {
    await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds
  }
} while (status.in_progress);

// Session complete
if (status.success) {
  console.log('Session completed successfully!');
  console.log('Files downloaded:', status.file_metadata);
  console.log('Agent summary:', status.final_message);
} else {
  console.log('Session failed');
}

import os
import time
from simplex import SimplexClient

client = SimplexClient(api_key=os.environ["SIMPLEX_API_KEY"])

workflow_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

# Start a workflow
result = client.run_workflow(
    workflow_id,
    variables={"patient_id": "P-12345", "insurance_provider": "Blue Cross"}
)

session_id = result["session_id"]

# Poll until complete
while True:
    status = client.get_session_status(session_id)

    if status.get("paused"):
        print("Session paused, waiting for resume...")
    elif status["in_progress"]:
        print("Session still running...")

    if status["in_progress"]:
        time.sleep(5)  # Wait 5 seconds
    else:
        break

# Session complete
if status["success"]:
    print("Session completed successfully!")
    print("Files downloaded:", status["file_metadata"])
    print("Agent summary:", status["final_message"])
else:
    print("Session failed")

Response structure

When polling session status, you’ll receive a response with the following fields:

boolean

required

true while the session is running, false when complete

boolean | null

required

Session outcome: null while running, true if successful, false if failed

object

Metadata set in the workflow definition

object

Custom metadata you provided when starting the session

array

Metadata for files downloaded during the session

Show properties

string

Name of the downloaded file

string

Presigned URL to download the file

number

Size of the file in bytes

string

ISO 8601 timestamp when the file was downloaded

array

Data collected by scraper actions during the session

object | null

Structured output fields from workflow execution. null while the session is in progress, populated at session close.

string | null

A summary of what the agent accomplished. null while the session is in progress, populated at session close.

boolean

true if the session is currently paused (waiting to be resumed), false otherwise

string

The pause key identifier if the session is paused, empty string otherwise

Polling with timeout

For production use, always implement a timeout to prevent infinite polling:

TypeScript
Python

import { SimplexClient, SessionStatusResponse } from 'simplex-ts';

async function pollWithTimeout(
  client: SimplexClient,
  sessionId: string,
  timeoutMs: number = 300000,  // 5 minutes default
  intervalMs: number = 5000    // 5 seconds default
): Promise<SessionStatusResponse> {
  const startTime = Date.now();

  while (Date.now() - startTime < timeoutMs) {
    const status = await client.getSessionStatus(sessionId);

    if (!status.in_progress) {
      return status;
    }

    await new Promise(resolve => setTimeout(resolve, intervalMs));
  }

  throw new Error(`Polling timed out after ${timeoutMs}ms`);
}

// Usage
try {
  const status = await pollWithTimeout(client, sessionId, 600000); // 10 min timeout
  console.log('Session result:', status.success);
} catch (error) {
  console.error('Polling failed:', error);
}

import time
from simplex import SimplexClient, SessionStatusResponse

def poll_with_timeout(
    client: SimplexClient,
    session_id: str,
    timeout_seconds: float = 300,  # 5 minutes default
    interval_seconds: float = 5    # 5 seconds default
) -> SessionStatusResponse:
    start_time = time.time()

    while time.time() - start_time < timeout_seconds:
        status = client.get_session_status(session_id)

        if not status["in_progress"]:
            return status

        time.sleep(interval_seconds)

    raise TimeoutError(f"Polling timed out after {timeout_seconds} seconds")

# Usage
try:
    status = poll_with_timeout(client, session_id, timeout_seconds=600)  # 10 min timeout
    print("Session result:", status["success"])
except TimeoutError as e:
    print("Polling failed:", e)

Monitoring file downloads

The file_metadata field updates in real-time as file_metadata are downloaded during the session. You can use this to track download progress:

TypeScript
Python

let lastFileCount = 0;

while (true) {
  const status = await client.getSessionStatus(sessionId);

  // Check for new file_metadata
  const currentFileCount = status.file_metadata?.length ?? 0;
  if (currentFileCount > lastFileCount) {
    const newFiles = status.file_metadata!.slice(lastFileCount);
    for (const file of newFiles) {
      console.log(`New file downloaded: ${file.filename} (${file.file_size} bytes)`);
    }
    lastFileCount = currentFileCount;
  }

  if (!status.in_progress) {
    break;
  }

  await new Promise(resolve => setTimeout(resolve, 5000));
}

import time

last_file_count = 0

while True:
    status = client.get_session_status(session_id)

    # Check for new file_metadata
    current_file_count = len(status["file_metadata"])
    if current_file_count > last_file_count:
        new_files = status["file_metadata"][last_file_count:]
        for file in new_files:
            print(f"New file downloaded: {file['filename']} ({file['file_size']} bytes)")
        last_file_count = current_file_count

    if not status["in_progress"]:
        break

    time.sleep(5)

​Usage

​Response structure

​Polling with timeout

​Monitoring file downloads

Usage

Response structure

Polling with timeout

Monitoring file downloads