Skip to main content
The Overten API separates two related concepts: a run is the durable record of a document and everything the agent learned while building it; a task is a single execution — one prompt, one agent turn, one output. Understanding this distinction lets you iterate on documents cheaply, because the agent never has to rediscover what it already built.

​
Why runs and tasks are separate

Every time a human edits a document in the Overten web app, the agent resumes where it left off — it remembers the bookmark IDs, sheet names, chart references, and structural decisions it made in earlier turns. The API works the same way. Keeping the run alive across calls means:
  • Turn 2 costs a fraction of turn 1, because the agent loads saved state instead of re-inspecting the full document.
  • Follow-up prompts are coherent — “move the revenue chart to the executive summary” works because the agent knows where both sections are.
  • You store one run_id alongside your own record; no extra state to maintain on your side.
Without run-level durability, every turn would rebuild from scratch.

​
Creating a run

You don’t create a run explicitly. The first call to any generation endpoint without a run_id creates one automatically: 
POST /excel/generate
{ "prompt": "Create a Q3 sales report" }

{
  "run_id": "run_01HXYZ...",
  "task_id": "task_01HXYZ...",
  "status": "completed",
  "download_url": "...",
  "edit_url": "...",
  "credits_used": 84,
  "duration_ms": 18432
}
Store the run_id with whatever record in your system represents this document — you’ll need it to resume.

​
Resuming a run

Pass the same run_id on any subsequent call to continue working on the same document: 
POST /excel/generate
{
  "run_id": "run_01HXYZ...",
  "prompt": "Now add a forecast tab for FY26"
}
When you resume a run:
  • The agent’s conversation state is restored from Overten’s durable store, keyed on run_id.
  • The last saved document bytes are reloaded into the same run context.
  • Your new prompt is appended as a fresh user message.
  • The agent continues, using everything it already built.
  • download_url in the response points to the updated document after this turn.

​
Tasks

Each call to a generation endpoint produces a task. In sync mode (the default), the task lifecycle is hidden — you wait for the response and get the finished result. In async mode, you receive a task_id immediately and poll for the result: 
POST /excel/generate
{ "prompt": "Build a 3-statement financial model", "async": true }

{
  "run_id": "run_01HXYZ",
  "task_id": "task_01HXYZ",
  "status": "queued"
}
Poll the task with: 
GET /tasks/task_01HXYZ

{
  "task_id": "task_01HXYZ",
  "run_id": "run_01HXYZ",
  "status": "running",
  "phase": "agent_turn",
  "turn_index": 3,
  "progress": 45,
  "created_at": "2026-04-17T11:20:00Z",
  "updated_at": "2026-04-17T11:23:12Z"
}
See Sync vs Async Generation for the full task state machine and polling strategy.

​
Listing runs

Retrieve recent runs for your organization with cursor-based pagination: 
GET /runs?limit=20&format=excel&status=completed

{
  "items": [
    {
      "run_id": "run_01HXYZ",
      "format": "excel",
      "status": "completed",
      "prompt": "Create a Q3 sales report with...",
      "credits_used": 84,
      "duration_ms": 18432,
      "created_at": "2026-04-17T11:20:00Z",
      "file_name": "workbook.xlsx"
    }
  ],
  "next_cursor": "run_01HXY..."
}
Pass next_cursor as the cursor query parameter on your next request to page forward. Results are newest-first.

​
Downloading a run’s output

Two options, both pointing at the same file: 
# Option A — JSON response with a signed download_url (24h TTL)
GET /runs/{run_id}

# Option B — 302 redirect straight to the signed URL
GET /runs/{run_id}/download
Option B is the right choice for a browser <a href> — the redirect saves an extra round-trip. Option A is useful when you need the full run metadata alongside the URL.

​
Exporting to other formats

Convert a completed run’s output to PDF, PNG, or other formats without re-running the agent: 
POST /runs/{run_id}/export
{ "format": "pdf" }

{
  "format": "pdf",
  "download_url": "...",
  "expires_at": "..."
}
Supported conversions:
SourceAvailable targets
xlsxpdf, csv, png, html
docxpdf, html, txt, odt
pptxpdf, png, odp
Exports are cached — calling /export?format=pdf twice for the same run only runs the conversion once.

​
Retention policy

Runs are retained for 30 days after their last task. After that window:
  • GET /runs/{run_id} still resolves for audit purposes, but the run’s status is marked expired.
  • Resuming an expired run returns 410 Gone. Start a fresh run instead — you cannot restore expired state.
  • The saved document bytes are removed from storage 30 days after expiry.
Enterprise customers can extend the default 30-day retention window. Contact support@overten.ai for details.