Skip to main content
Runs are asynchronous. POST /v1/run returns a run_id immediately; you poll GET /v1/run/{run_id} until the run reaches a terminal status. 
curl https://api.getspine.ai/v1/run/<run_id> \
  -H "X-API-KEY: sk_spine_..."
Runs average 10–20 minutes; complex research can take up to 2 hours. Poll every 15–30 seconds, or use a backoff (start at 15 s, grow to 60 s) to reduce traffic on longer runs.

​
Run statuses

StatusMeaningTerminal?
runningAgents still executingNo
completedAll agents finished, results availableYes
partialSome blocks failed but usable results existYes
failedRun failed — see errors arrayYes

​
Response shapes

​
While running

{
  "success": true,
  "data": {
    "run_id": "uuid",
    "status": "running",
    "canvas_id": "uuid",
    "progress": {
      "tasks_completed": 3,
      "tasks_total": 8,
      "elapsed_ms": 480000
    }
  }
}

​
Completed

{
  "success": true,
  "data": {
    "run_id": "uuid",
    "status": "completed",
    "canvas_id": "uuid",
    "duration_ms": 927300,
    "result": {
      "final_output": "synthesized answer or agent summary",
      "artifacts": [
        {
          "id": "node-uuid",
          "type": "docx",
          "name": "Q1_Report.docx",
          "download_url": "https://...",
          "size_bytes": 245000
        }
      ]
    },
    "metadata": {
      "template_used": "report",
      "models_used": ["anthropic/claude-sonnet-4-6"],
      "credits_consumed": 45
    }
  }
}

​
Failed

{
  "success": true,
  "data": {
    "run_id": "uuid",
    "status": "failed",
    "errors": [{ "error": "Agent execution failed" }]
  }
}

​
Canvas introspection

Spine runs are fully auditable. Once a run has a canvas_id, you can see exactly what the agents did — both programmatically and visually.

​
Inspect via the API

Every block includes its full content output and sources, so you can verify every intermediate artifact — not just the final deliverable.

​
Open the run in a canvas

Each canvas_id also has a visual counterpart at https://app.getspine.ai/canvas/{canvas_id} — open it to see the block DAG rendered, click into any block to inspect its output, and watch the agent tree as a graph rather than JSON. Same data, two surfaces: use whichever fits your workflow.