Runs

A run represents one execution of the agent loop on a project. Runs are created automatically when you POST a prompt; you poll them to track progress.

Get a run

http
GET /api/v1/runs/{id}

json
{
  "id": "…",
  "status": "RUNNING" | "AWAITING_INPUT" | "DONE" | "ERROR" | "CANCELED",
  "modelId": "claude-opus-4-7",
  "error": null,
  "startedAt": "…",
  "finishedAt": "…",
  "events": [
    { "seq": 1, "type": "RUN_STARTED", "payload": { "modelId": "…" } },
    { "seq": 2, "type": "TOOL_CALL", "payload": { "toolName": "createOrUpdateFiles", "input": {…} } },
    { "seq": 3, "type": "TOOL_RESULT", "payload": { "toolName": "createOrUpdateFiles", "output": {…} } },
    { "seq": 4, "type": "DONE", "payload": { "summary": "…", "title": "…", "sandboxUrl": "…" } }
  ],
  "result": {
    "summary": "Built a counter app with two buttons.",
    "title": "Counter app",
    "sandboxUrl": "https://3000-…-e2b.app",
    "files": { "app/page.tsx": "…", "lib/utils.ts": "…" }
  }
}

Statuses

QUEUED — created, not started yet.
RUNNING — agent loop is executing.
AWAITING_INPUT — agent emitted design questions; resume by submitting answers from the web app.
DONE — completed successfully; result is populated.
ERROR — failed; error contains the message.
CANCELED — manually canceled.

Live updates (web app only)

For real-time updates from the dashboard, the web app subscribes to GET /api/agent/runs/{id}/events as a Server-Sent Events stream. Public-API consumers should poll GET /api/v1/runs/{id} every 2–3 seconds.