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

# Generate asynchronously

> Queue Open Source presentation generation and monitor its task status without holding one request open.

Use asynchronous generation for longer decks, background jobs, or integrations that cannot keep an HTTP connection open until export finishes.

## 1. Queue the presentation

Send the normal generation body to `POST /api/v1/ppt/presentation/generate/async`:

```bash theme={null}
curl --request POST \
  --url "$PRESENTON_URL/api/v1/ppt/presentation/generate/async" \
  --user "$PRESENTON_USERNAME:$PRESENTON_PASSWORD" \
  --header 'Content-Type: application/json' \
  --data '{
    "content": "Create an FY2027 operating-plan review for a B2B SaaS board. Current ARR is $18.2M, net revenue retention is 118%, gross margin is 76%, enterprise pipeline coverage is 2.8x, and annual logo churn increased from 7% to 9%. Management must decide whether to fund a second enterprise sales pod and whether to move $600K from brand programs into customer retention.",
    "instructions": "Create an executive scorecard, explain the growth and churn trade-offs, compare the two capital-allocation decisions, and finish with a recommendation and measurable next steps. Preserve every supplied value exactly.",
    "tone": "professional",
    "n_slides": 8,
    "template": "general",
    "export_as": "pptx"
  }'
```

The initial response includes a task ID:

```json theme={null}
{
  "id": "task-9a827c13f4",
  "type": "presentation.generate",
  "status": "pending",
  "message": "Queued for generation",
  "data": {
    "created_slides": 0,
    "remaining_slides": 8
  }
}
```

Persist `id` before returning control to the caller.

## 2. Poll task status

```bash theme={null}
curl --request GET \
  --url "$PRESENTON_URL/api/v1/ppt/presentation/status/task-9a827c13f4" \
  --user "$PRESENTON_USERNAME:$PRESENTON_PASSWORD"
```

| Status       | Meaning                            | Action                                 |
| ------------ | ---------------------------------- | -------------------------------------- |
| `pending`    | Waiting to start                   | Continue polling                       |
| `processing` | Slides or export are being created | Continue polling with backoff          |
| `completed`  | Generation and export finished     | Stop polling                           |
| `error`      | Generation failed                  | Stop and inspect `error` and `message` |

The beta status response reports progress in `data`. If your integration needs the completed presentation payload pushed to it, set `trigger_webhook` to `true` and subscribe to the presentation-generation webhook events.

## 3. Poll with a deadline

```python theme={null}
import os
import random
import time

import requests

base_url = os.environ.get("PRESENTON_URL", "http://localhost:5001")
auth = (
    os.environ["PRESENTON_USERNAME"],
    os.environ["PRESENTON_PASSWORD"],
)


def wait_for_task(task_id: str, timeout_seconds: int = 900) -> dict:
    deadline = time.monotonic() + timeout_seconds
    delay = 2.0

    while time.monotonic() < deadline:
        response = requests.get(
            f"{base_url}/api/v1/ppt/presentation/status/{task_id}",
            auth=auth,
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()

        if task["status"] == "completed":
            return task
        if task["status"] == "error":
            raise RuntimeError(task.get("error") or task.get("message"))

        time.sleep(delay + random.uniform(0, 0.5))
        delay = min(delay * 1.5, 15.0)

    raise TimeoutError(f"Task {task_id} did not finish before the deadline")
```

## Reliability checklist

* Use one poller per task and persist the latest status.
* Add jitter and cap the delay between requests.
* Enforce a total deadline in addition to per-request timeouts.
* Stop polling on both terminal states.
* Never log Basic-auth credentials, prompts containing secrets, or source documents.
* Avoid blind submission retries that can create duplicate presentations.

<Card title="Synchronous API tutorial" icon="brackets-curly" href="/open-source/v0.9.0-beta/tutorials/generate-with-api">
  Review generation fields, document upload, responses, and production practices.
</Card>