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.
POST /v1/run returns a run_id immediately; you poll GET /v1/run/{run_id} until the run reaches a terminal status.
Run statuses
Response shapes
While running
Completed
Failed
Canvas introspection
Spine runs are fully auditable. Once a run has acanvas_id, you can see exactly what the agents did — both programmatically and visually.
Inspect via the API
GET /v1/canvas/{canvas_id}/dag— the block graph (nodes + edges). Shows which blocks the agents created and how they’re connected.GET /v1/canvas/{canvas_id}/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}— a single task with its children. Drill into one step of the agent’s reasoning.
content output and sources, so you can verify every intermediate artifact — not just the final deliverable.
Open the run in a canvas
Eachcanvas_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.