> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getspine.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Polling and status

> How to poll a run and interpret the response at each state.

<Note>
  Prefer webhooks for app integrations. Instead of polling on a timer, you can register a webhook URL to receive a signed callback the moment a run completes. See [Webhooks](/api-reference/concepts/webhooks).
</Note>

Runs are asynchronous. [`POST /v1/run`](/api-reference/endpoints/create-run) returns a `run_id` immediately; you poll [`GET /v1/run/{run_id}`](/api-reference/endpoints/get-run) until the run reaches a terminal status.

```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
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

| Status      | Meaning                                     | Terminal? |
| ----------- | ------------------------------------------- | --------- |
| `running`   | Agents still executing                      | No        |
| `completed` | All agents finished, results available      | Yes       |
| `partial`   | Some blocks failed but usable results exist | Yes       |
| `failed`    | Run failed — see `errors` array             | Yes       |

## Response shapes

### While running

```json theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
{
  "success": true,
  "data": {
    "run_id": "uuid",
    "status": "running",
    "canvas_id": "uuid",
    "progress": {
      "tasks_completed": 3,
      "tasks_total": 8,
      "elapsed_ms": 480000
    }
  }
}
```

### Completed

```json theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
{
  "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

```json theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
{
  "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

* [`GET /v1/canvas/{canvas_id}/dag`](/api-reference/endpoints/get-canvas-dag) — the block graph (nodes + edges). Shows which blocks the agents created and how they're connected.
* [`GET /v1/canvas/{canvas_id}/tasks`](/api-reference/endpoints/get-canvas-tasks) — the full task hierarchy (parent-task → persona-task → tool-call-task). Reveals how the prompt was decomposed, which personas ran, and every tool call they made.
* [`GET /v1/canvas/{canvas_id}/tasks/{task_id}`](/api-reference/endpoints/get-task) — a single task with its children. Drill into one step of the agent's reasoning.

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.