> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poesius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Status Polling

> Best practices for polling presentation status

## Status Polling Basics

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

## Status Values

| Status       | Description                              | Action                |
| ------------ | ---------------------------------------- | --------------------- |
| `pending`    | Generation has started but not completed | Continue polling      |
| `processing` | Content and slides are being generated   | Continue polling      |
| `completed`  | Presentation is ready for download       | Download presentation |
| `failed`     | Generation failed                        | Check error details   |

## Basic Polling Pattern

### Bash Example

```bash theme={null}
# 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

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
# Instead of polling, set up a webhook endpoint
# that receives status updates when generation completes
```

<Card title="Check Status" icon="circle-check" href="/api/check-status">
  Learn more about checking status
</Card>

<Card title="Error Handling Overview" icon="triangle-exclamation" href="/errors/overview">
  See other error handling guides
</Card>