Skip to main content

​
Status Polling Basics

Since presentation generation is asynchronous, you need to poll the status endpoint to check when generation is complete.

​
Status Values

StatusDescriptionAction
pendingGeneration has started but not completedContinue polling
processingContent and slides are being generatedContinue polling
completedPresentation is ready for downloadDownload presentation
failedGeneration failedCheck error details

​
Basic Polling Pattern

​
Bash Example

# Poll every 5-10 seconds
while true; do
  STATUS=$(curl -s -X GET \
    "https://poe.poesius.com/api/v1/presentations/{presentation_id}" \
    -H "X-API-Key: pk_your_api_key_here" | jq -r '.status')
  
  echo "Status: $STATUS"
  
  if [ "$STATUS" = "completed" ]; then
    echo "Presentation ready!"
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Generation failed!"
    exit 1
  fi
  
  sleep 5
done

​
Python Example

import time
import requests

def poll_presentation_status(presentation_id, api_key, max_wait=300):
    """Poll for presentation status until completed or failed"""
    start_time = time.time()
    
    while time.time() - start_time < max_wait:
        response = requests.get(
            f"https://poe.poesius.com/api/v1/presentations/{presentation_id}",
            headers={"X-API-Key": api_key}
        )
        response.raise_for_status()
        data = response.json()
        
        status = data.get("status")
        print(f"Status: {status}")
        
        if status == "completed":
            return data
        elif status == "failed":
            raise Exception(f"Generation failed: {data.get('error')}")
        
        time.sleep(5)  # Wait 5 seconds before next poll
    
    raise TimeoutError("Presentation generation timed out")

​
Best Practices

​
Poll Interval

  • Recommended: 5-10 seconds between polls
  • Too Frequent: May hit rate limits
  • Too Infrequent: Slower user experience

​
Timeout Handling

Always set a maximum wait time: 
MAX_WAIT = 300  # 5 minutes

start_time = time.time()
while time.time() - start_time < MAX_WAIT:
    # Poll status
    ...

​
Exponential Backoff

For better efficiency, use exponential backoff: 
import time

poll_interval = 2  # Start with 2 seconds
max_interval = 30  # Max 30 seconds

while True:
    status = check_status()
    
    if status == "completed":
        break
    elif status == "failed":
        raise Exception("Generation failed")
    
    time.sleep(poll_interval)
    poll_interval = min(poll_interval * 1.5, max_interval)

​
Error Handling

def poll_with_error_handling(presentation_id, api_key, max_wait=300):
    """Poll with comprehensive error handling"""
    start_time = time.time()
    retry_count = 0
    max_retries = 3
    
    while time.time() - start_time < max_wait:
        try:
            response = requests.get(
                f"https://poe.poesius.com/api/v1/presentations/{presentation_id}",
                headers={"X-API-Key": api_key},
                timeout=10
            )
            response.raise_for_status()
            data = response.json()
            
            status = data.get("status")
            
            if status == "completed":
                return data
            elif status == "failed":
                raise Exception(f"Generation failed: {data.get('error')}")
            
            retry_count = 0  # Reset on success
            time.sleep(5)
            
        except requests.exceptions.RequestException as e:
            retry_count += 1
            if retry_count > max_retries:
                raise Exception(f"Failed to poll status after {max_retries} retries: {e}")
            time.sleep(5 * retry_count)  # Exponential backoff
    
    raise TimeoutError("Presentation generation timed out")

​
Progress Indicators

Show progress to users: 
def poll_with_progress(presentation_id, api_key):
    """Poll with progress indication"""
    dots = 0
    
    while True:
        response = requests.get(
            f"https://poe.poesius.com/api/v1/presentations/{presentation_id}",
            headers={"X-API-Key": api_key}
        )
        data = response.json()
        status = data.get("status")
        
        # Show progress
        dots = (dots + 1) % 4
        print(f"\rGenerating{'.' * dots}   ", end="", flush=True)
        
        if status == "completed":
            print("\n✓ Generation complete!")
            return data
        elif status == "failed":
            print("\n✗ Generation failed!")
            raise Exception(f"Error: {data.get('error')}")
        
        time.sleep(5)

​
Webhook Alternative

For production applications, consider using webhooks (if available) instead of polling: 
# Instead of polling, set up a webhook endpoint
# that receives status updates when generation completes

Check Status

Learn more about checking status

Error Handling Overview

See other error handling guides