Skip to main content
The API models two related but distinct things:
  • A run is a durable document. It persists across many calls and retains what the agent “knows” about what it built.
  • A task is one execution against a run — the act of submitting a prompt, running the agent, and producing output.
A run can have many tasks. The first task creates the run; subsequent tasks (when you pass run_id) resume it.

​
Why separate them

In the web app, agents work on a document over many chat turns. The API mirrors that: turn 1 creates the scaffold, turn 2 adds a section, turn 3 changes the branding — and each turn should cost a fraction of turn 1 because the agent remembers what it built. Without run-level durability, every turn would re-inspect the document from scratch. With it, bookmark IDs, sheet names, chart references — everything the agent learned in turn 1 — are still in context for turn 5.

​
Creating a run (implicit)

Every generation endpoint creates a run if you don’t pass run_id:
The run_id is yours to keep. Store it with whatever record in your system represents this document.

​
Resuming a run

Pass the same run_id on the next call and add a new prompt:
Semantics:
  • The agent’s conversation state is restored from our durable store, keyed on run_id.
  • The last saved document bytes are reloaded into the same run context the agent was using.
  • The new prompt is appended as a fresh user message.
  • The agent continues, using everything it already built.
  • download_url points to the new saved state after this turn.

​
Tasks

Each invocation produces a task. In sync mode the task shape is hidden — you get the finished result back directly. In async mode you get a task_id to poll:
Then:
See Async vs sync for the full state machine.

​
Listing runs

Returns the most recent runs for your org, newest first. Cursor-based pagination via the next_cursor field.

​
Downloading

Two options per run:
Option B is what you want from a browser <a href> — no extra round-trip.

​
Exporting to other formats

Convert a run’s output to PDF, PNG, etc. via POST /runs//export:
Supported conversions: Exports are cached — calling /export?format=pdf twice for the same run only runs the conversion once.

​
Retention

Runs are retained for 30 days after their last task. After that:
  • The run_id still resolves via GET /runs/{run_id} for audit, but its state is marked expired.
  • Resuming an expired run returns 410 gone. Start a fresh run instead.
  • The saved document bytes are removed from storage 30 days after expiry.
Enterprise customers can extend retention — contact us.