Skip to main content
Every generation endpoint — /excel/generate, /word/generate, /slides/generate, /slides/outline, and the /text/* endpoints — supports two execution modes. Sync blocks until the document is ready; async returns a task_id immediately and lets you poll or receive a webhook when the job finishes. Choose based on the expected job size and where your code runs.

​
Sync (default)

The HTTP connection stays open until the document is ready, up to a 300-second (5-minute) ceiling. Most single-sheet spreadsheets, short memos, and small decks land well inside that window. 
POST /excel/generate
{ "prompt": "Create a sales report" }

200 OK
{
  "run_id": "run_...",
  "task_id": "task_...",
  "status": "completed",
  "download_url": "...",
  "edit_url": "...",
  "summary": "...",
  "credits_used": 84,
  "duration_ms": 187707
}
Overten runs real AI agents, not templates. Even a simple prompt typically takes 90 seconds to 3 minutes because the agent plans, writes, verifies, and often refines across multiple internal turns. Expect this, and show a progress indicator rather than a short timeout.
Use sync when:
  • You’re prototyping and want to keep the integration simple.
  • The prompt is small enough to land under 300s — a single-sheet workbook, a short memo, or a 3–5 slide deck.
  • Your caller (a browser, Zapier, a webhook handler) can hold the connection open.

​
Auto-promotion to async

If a sync job is still running at the 300-second ceiling, Overten automatically promotes it to async and returns 202 Accepted with a task_id: 
202 Accepted
{
  "run_id": "run_...",
  "task_id": "task_...",
  "status": "queued",
  "message": "Sync ceiling (300s) exceeded; continuing asynchronously."
}
You then poll /tasks/{task_id} exactly as you would for an explicit async call. This happens most often with complex multi-sheet financial models, long decks, and long-form reports.

​
Async

Set "async": true in the request body. The endpoint returns immediately with a task_id; the agent runs in the background. 
POST /excel/generate
{
  "prompt": "Build a 3-statement financial model",
  "async": true
}

202 Accepted
{
  "run_id": "run_...",
  "task_id": "task_...",
  "status": "queued"
}
Use async when:
  • The job is large — a full deck, a multi-sheet financial model, a long-form report.
  • Your caller is a background worker or cron job.
  • You want to receive results via webhook instead of holding a connection open.

​
Task states

Every task moves through this state machine: 
queued → running → completed | failed | cancelled | expired
StatusTerminal?Meaning
queuedNoAccepted, waiting for a worker
runningNoAgent is actively executing
completedYesSuccess — result is populated
failedYesUnrecoverable error — error is populated
cancelledYesClient cancelled or server shutdown mid-run
expiredYesQueued for more than 24 hours without being picked up
While running, the phase field gives you a finer-grained sub-state. Common values include preflight, agent_turn, and uploading_result. The exact set of phase values may expand over time — use them for display purposes only and don’t branch critical logic off them. The progress field (integer 0–100) is an approximate completion percentage. Use it to drive progress bars; don’t branch logic off it.

​
Polling

Check the status of any task with: 
GET /tasks/{task_id}
A task in progress: 
{
  "task_id": "task_...",
  "run_id": "run_...",
  "status": "running",
  "phase": "agent_turn",
  "turn_index": 3,
  "progress": 45
}
A completed task: 
{
  "task_id": "task_...",
  "status": "completed",
  "result": {
    "download_url": "...",
    "edit_url": "...",
    "summary": "Built a 3-statement model with FY26-FY30 projections.",
    "artifacts": []
  },
  "credits_used": 127,
  "duration_ms": 54321
}

​
Polling strategy

  • Initial wait: 2–5 seconds. Most tasks move from queued to running within a second, but the actual agent work is what takes time.
  • Backoff: Linear or exponential, capped at 10 seconds between polls. More frequent polling doesn’t make the agent finish faster — it only burns your rate-limit budget.
  • Overall timeout: Plan for up to 30 minutes for heavy jobs. Financial models, long-form reports, and decks with many generated charts regularly run 10–25 minutes end-to-end.
import time, requests

headers = {"Authorization": f"Bearer {API_KEY}"}

# Poll for up to ~30 minutes, capped at 10s per interval
for attempt in range(200):
    task = requests.get(f"{API}/tasks/{task_id}", headers=headers).json()
    if task["status"] in {"completed", "failed", "cancelled", "expired"}:
        break
    time.sleep(min(2 + attempt * 0.5, 10))
For production workloads, replace polling with webhooks. Polling a task for 20 minutes produces 240 wasted HTTP calls per job — manageable in a dev script, noisy at scale. See Webhooks to set up push delivery.

​
Webhooks as an alternative to polling

Pass webhook_url alongside async: true and Overten will POST the result to your endpoint when the task finishes, skipping polling entirely: 
POST /excel/generate
{
  "prompt": "...",
  "async": true,
  "webhook_url": "https://myapp.example.com/webhooks/overten"
}
See Webhooks for HMAC signature verification, event types, and the retry schedule.

​
Choosing a mode

Sync. Show a spinner, wait for the response, then redirect to the download_url or embed the edit_url. The call promotes to async automatically if it runs long.
Async + webhooks. Submit all jobs with async: true; a webhook fires your queue when each finishes. Your worker downloads and files them without holding any HTTP connections open.
Sync. A short memo or single-sheet summary typically lands in 90 seconds to 3 minutes — fast enough for a human to wait with a spinner.
Sync each step, reuse run_id. Subsequent calls resume from saved state, so they’re cheaper — but each step is still a real agent turn (often 60 seconds or more), so don’t expect instant responses.
Async + webhooks. These jobs commonly take 10–25 minutes. Blocking from a browser doesn’t work at that scale, and polling for 20 minutes from a client is wasteful. Submit with async: true and webhook_url, then let Overten call you when it’s done.