> ## 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.
# Get a run
> Poll the current status of a run. Returns progress while `running` and
the full result (final output + downloadable artifacts + metadata)
once `completed`.
Async runs need an API key and typically take 10–20 minutes (up to 2 hours
for complex research). Get \$5 of free credits on signup — no subscription,
\$1 = 1,000 credits. The developer playground handles auth, polling, and
artifact downloads for you.
## OpenAPI
````yaml GET /v1/run/{run_id}
openapi: 3.1.0
info:
title: Spine API
version: 1.0.0
summary: The highest-quality research API — multi-agent canvas orchestration.
description: |
The Spine API delivers the highest-quality research available, ranked #1 on
GAIA Level 3. Submit a prompt (with optional files, a template, or an
explicit block configuration) to kick off an async multi-agent canvas run,
and poll for the generated artifacts, DAG, and task tree.
All endpoints are authenticated via the `X-API-KEY` header. Create a key
from the [Spine developer portal](https://platform.getspine.ai).
contact:
name: Spine support
email: support@getspine.ai
url: https://platform.getspine.ai
servers:
- url: https://api.getspine.ai
description: Production
security:
- apiKey: []
tags:
- name: Runs
description: Create and poll canvas runs.
- name: Canvas
description: Inspect the generated canvas DAG and task tree.
paths:
/v1/run/{run_id}:
get:
tags:
- Runs
summary: Get run status and results
description: |
Poll the current status of a run. Returns progress while `running` and
the full result (final output + downloadable artifacts + metadata)
once `completed`.
operationId: getRun
parameters:
- $ref: '#/components/parameters/RunId'
responses:
'200':
description: Current run state.
content:
application/json:
schema:
$ref: '#/components/schemas/GetRunResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-codeSamples:
- lang: curl
label: curl
source: |
curl https://api.getspine.ai/v1/run/ \
-H "X-API-KEY: sk_spine_..."
- lang: python
label: Python
source: |
import requests
r = requests.get(
f"https://api.getspine.ai/v1/run/{run_id}",
headers={"X-API-KEY": "sk_spine_..."},
)
print(r.json()["data"]["status"])
- lang: javascript
label: Node
source: |
const res = await fetch(`https://api.getspine.ai/v1/run/${runId}`, {
headers: { "X-API-KEY": "sk_spine_..." },
});
const { data } = await res.json();
console.log(data.status);
components:
parameters:
RunId:
name: run_id
in: path
required: true
description: The run identifier returned by `POST /v1/run`.
schema:
type: string
format: uuid
schemas:
GetRunResponse:
type: object
required:
- success
- data
properties:
success:
type: boolean
const: true
data:
$ref: '#/components/schemas/Run'
Run:
type: object
required:
- run_id
- status
properties:
run_id:
type: string
format: uuid
status:
$ref: '#/components/schemas/RunStatus'
canvas_id:
type: string
format: uuid
progress:
$ref: '#/components/schemas/RunProgress'
duration_ms:
type: integer
description: Set once the run reaches a terminal state.
result:
$ref: '#/components/schemas/RunResult'
metadata:
$ref: '#/components/schemas/RunMetadata'
errors:
type: array
items:
type: object
properties:
error:
type: string
Error:
type: object
required:
- success
- error
properties:
success:
type: boolean
const: false
error:
type: string
description: Human-readable error message.
RunStatus:
type: string
enum:
- running
- completed
- partial
- failed
RunProgress:
type: object
description: Present while `status` is `running`.
properties:
tasks_completed:
type: integer
tasks_total:
type: integer
elapsed_ms:
type: integer
RunResult:
type: object
description: Present when `status` is `completed` or `partial`.
properties:
final_output:
type: string
description: Synthesized answer or agent summary.
artifacts:
type: array
items:
$ref: '#/components/schemas/Artifact'
RunMetadata:
type: object
description: Present when `status` is `completed`.
properties:
template_used:
$ref: '#/components/schemas/Template'
models_used:
type: array
items:
type: string
example:
- anthropic/claude-sonnet-4-6
credits_consumed:
type: integer
Artifact:
type: object
description: A downloadable file produced by a block on this canvas.
required:
- id
- type
- name
- download_url
properties:
id:
type: string
format: uuid
type:
type: string
description: File extension (docx, xlsx, pptx, html, png, …).
example: docx
name:
type: string
example: Q1_Report.docx
download_url:
type: string
format: uri
size_bytes:
type: integer
Template:
type: string
description: Preset that controls which block types agents are allowed to create.
enum:
- auto
- deep_research
- report
- slides
- memo
- excel
- app
- landing_page
responses:
BadRequest:
description: Malformed request (bad template, blocks, or UUID).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalidTemplate:
value:
success: false
error: >-
Invalid template: foo. Valid templates: app, auto,
deep_research, excel, landing_page, memo, report, slides
Unauthorized:
description: Missing, invalid, or revoked API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missingKey:
value:
success: false
error: X-API-KEY header required
NotFound:
description: Resource does not exist or belongs to another account.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
runNotFound:
value:
success: false
error: 'Run not found: 550e8400-e29b-41d4-a716-446655440000'
securitySchemes:
apiKey:
type: apiKey
in: header
name: X-API-KEY
description: |
An API key from the Spine developer portal. Keys are prefixed with
`sk_spine_` and shown only once at creation. Keep them server-side.
````