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 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: { url: 'https://example.com' } }); 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 ); } 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 = { "url" : "https://example.com" } ) 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" ]) else : print ( "Session failed" )
Response structure When polling session status, you’ll receive a response with the following fields:
true while the session is running, false when complete
Session outcome: null while running, true if successful, false if failed
Metadata set in the workflow definition
Custom metadata you provided when starting the session
Metadata for files downloaded during the session Name of the downloaded file
Presigned URL to download the file
Size of the file in bytes
ISO 8601 timestamp when the file was downloaded
Data collected by scraper actions during the session
Structured output fields from workflow execution. null while the session is in progress, populated at session close.
true if the session is currently paused (waiting to be resumed), false otherwise
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:
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:
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 )
