> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # List runs ## OpenAPI ````yaml api-reference/openapi.json GET /v1/runs openapi: 3.1.0 info: title: Spiral API version: '1' description: >- 1. Retry automatically only on network errors and timeouts (same `Idempotency-Key`) and on the codes below. `retryable` and `x-should-retry` on the answer always win over this table (for example `RATE_LIMITED` is not retryable once the `day` policy is exhausted). Every other code needs a change before the request is sent again. | Code | HTTP | Retry | Wait | |---|---|---|---| | INSUFFICIENT_BALANCE | 402 | only when the problem says `retryable: true`, with the same `Idempotency-Key` | `Retry-After` (30 s by default) | | IDEMPOTENCY_IN_PROGRESS | 409 | yes, with the same `Idempotency-Key` | `Retry-After` (1 s by default) | | RATE_LIMITED | 429 | yes | `Retry-After` | | CONCURRENCY_LIMITED | 429 | yes | `Retry-After` (2 s by default) | | QUEUE_FULL | 429 | yes | `Retry-After` (2 s by default) | | INTERNAL_ERROR | 500 | yes, with the same `Idempotency-Key` | backoff (rule 2) | | BILLING_UNAVAILABLE | 503 | yes, with the same `Idempotency-Key` | `Retry-After` (5 s by default) | | SCHEMA_UNAVAILABLE | 503 | yes | `Retry-After` (10 s by default) | | PROVIDER_PAUSED | 503 | yes | `Retry-After` (60 s by default) | | MODEL_PAUSED | 503 | yes | `Retry-After` (60 s by default) | | SERVICE_UNAVAILABLE | 503 | yes, with the same `Idempotency-Key` | `Retry-After` (5 s by default) | 2. Backoff: capped exponential with full jitter, `sleep = random(0, min(30 s, 1 s × 2^attempt))`, at most 4 retries and about 2 minutes in total for a create. 3. Retry-After is a floor: wait at least that long (add 0–20 % jitter). Magica never sends more than 60 s. 4. Keys: send a UUIDv4 `Idempotency-Key` on every `POST /v1/runs` and store it with your task before sending. Reuse it for every retry of the same intent, including after a restart; a replay returns the original run with `Idempotent-Replayed: true`, never a second run or charge. Use a new key only to start a new run deliberately. A key is remembered for 3 days, then may start a new run. 5. Unknown outcome of a create (timeout, connection reset): retry with the same key. Never switch to a new key until the first request is known not to have created a run. 6. Failed runs: start at most one new run (new key), and only when `error.retryable` is true. `PROVIDER_OUTCOME_UNKNOWN` is not retryable: check your own results first, because the provider may have done the work. 7. Polling: prefer webhooks. Otherwise use `GET /v1/runs/{id}?wait_seconds=30`, or poll by `Retry-After` on 202 and running responses; without it start at 1 s (search and scrape), 2 s (images), 5 s (video and audio), back off × 1.5 up to 30 s, and stop at a final status. Polling has its own rate-limit policy (`poll`), so it never consumes create quota. 8. Webhooks: verify the signature over the raw body with your org's signing secret (any Standard Webhooks library; during a secret rotation the header carries two signatures and either verifies); answer 2xx fast and do the work afterwards (a delivery that takes over 10 s is re-sent); ignore event types you do not handle (types are added over time); dedupe on `webhook-id` for at least 7 days (every re-send carries the same one); on `truncated: true` read the run with `GET /v1/runs/{id}` (the body left out `output` to stay under receiver limits); ignore a delivery whose run `sequence` is lower than one already applied; download outputs within 24 hours. A webhook is sent right after the run is charged, so it usually carries the final charge (`sequence` 4); when the provider's bill comes later it carries `cost.state: held` (`sequence` 3) and the final charge is on `GET /v1/runs/{id}` (`sequence` 4). No separate billing event is sent. 9. Runs cannot be canceled after submission. Poll the run or wait for its configured terminal webhook. servers: - url: https://api.spiral.ai security: [] paths: /v1/runs: get: tags: - Runs summary: This org's runs, newest first. operationId: list-runs parameters: - name: status in: query required: false schema: description: Public status. type: string enum: - queued - running - completed - failed - canceled description: Public status. - name: provider in: query required: false schema: description: Provider id. type: string description: Provider id. - name: cursor in: query required: false schema: description: Opaque; the `next_cursor` of the previous page. type: string description: Opaque; the `next_cursor` of the previous page. - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 description: 1–`list.max_limit` (100), default `list.default_limit` (20). description: 1–`list.max_limit` (100), default `list.default_limit` (20). responses: '200': description: A page of runs. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' Cache-Control: $ref: '#/components/headers/Cache-Control' content: application/json: schema: type: object properties: object: type: string const: list items: type: array items: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ object: type: string const: run status: type: string enum: - queued - running - completed - failed - canceled provider: type: string model: type: string output: anyOf: - type: object properties: items: type: array items: type: object properties: type: type: string enum: - image - video - audio - text - json - 3d url: type: string format: uri mime_type: type: string size_bytes: type: integer minimum: -9007199254740991 maximum: 9007199254740991 width: type: integer minimum: -9007199254740991 maximum: 9007199254740991 height: type: integer minimum: -9007199254740991 maximum: 9007199254740991 duration_seconds: type: number kind: type: string data: {} expires_at: type: string description: RFC 3339 timestamp field: type: string source: type: string const: provider notice: type: string error: type: object properties: code: type: string enum: - OUTPUT_UNAVAILABLE - OUTPUT_TOO_LARGE message: type: string required: - code - message required: - type expired: type: boolean dropped_count: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - items - expired - type: 'null' usage: anyOf: - type: object properties: units: type: array items: type: object properties: unit: type: string quantity: type: number required: - unit - quantity required: - units - type: 'null' cost: type: object properties: currency: type: string const: USD state: type: string enum: - held - settled - released estimated: type: object properties: amount: type: string amount_micros: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - amount - amount_micros charged: anyOf: - type: object properties: amount: type: string amount_micros: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - amount - amount_micros - type: 'null' required: - currency - state - estimated - charged charge_reason: anyOf: - type: string enum: - provider_billed_failure - provider_billed_cancel - type: 'null' timings: type: object properties: created_at: type: string description: RFC 3339 timestamp started_at: anyOf: - type: string description: RFC 3339 timestamp - type: 'null' completed_at: anyOf: - type: string description: RFC 3339 timestamp - type: 'null' required: - created_at - started_at - completed_at error: anyOf: - type: object properties: code: type: string message: type: string retryable: type: boolean errors: type: array items: type: object properties: pointer: type: string message: type: string reason: type: string enum: - unknown_field - missing_required - wrong_type - not_in_enum - below_minimum - above_maximum - not_multiple_of - too_short - too_long - too_few_items - too_many_items - pattern_mismatch - invalid_format - no_matching_variant - invalid_combination - control_field - invalid_value - file_too_large - unsupported_media_type - duration_too_long - duration_too_short - resolution_too_low - resolution_too_high - unreachable - file_not_found - content_policy - provider_refused expected: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object propertyNames: type: string additionalProperties: type: - string - number - boolean - 'null' received: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object propertyNames: type: string additionalProperties: type: - string - number - boolean - 'null' allowed: type: array items: type: - string - number - boolean - 'null' required: - pointer - message required: - code - message - retryable - type: 'null' metadata: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' idempotency_key: type: - string - 'null' app: anyOf: - type: object properties: id: type: string url: type: string title: type: - string - 'null' required: - id - url - title - type: 'null' sequence: anyOf: - type: number const: 1 - type: number const: 2 - type: number const: 3 - type: number const: 4 links: type: object properties: self: type: string required: - self required: - id - object - status - provider - model - output - usage - cost - charge_reason - timings - error - metadata - idempotency_key - app - sequence - links next_cursor: type: - string - 'null' has_more: type: boolean required: - object - items - next_cursor - has_more '400': description: 'Problem: INVALID_REQUEST.' headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '401': description: 'Problem: UNAUTHENTICATED, API_KEY_REVOKED, API_KEY_EXPIRED.' headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '403': description: 'Problem: ORG_SUSPENDED, PERMISSION_DENIED.' headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '405': description: 'Problem: METHOD_NOT_ALLOWED.' headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' Allow: $ref: '#/components/headers/Allow' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '429': description: 'Problem: RATE_LIMITED.' headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' Retry-After: $ref: '#/components/headers/Retry-After' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '500': description: 'Problem: INTERNAL_ERROR.' headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '503': description: 'Problem: SERVICE_UNAVAILABLE.' headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' Retry-After: $ref: '#/components/headers/Retry-After' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - bearer: [] components: headers: X-Request-Id: description: >- `req_`; equals `request_id` in problems and the log context. Every response. schema: type: string RateLimit-Policy: description: >- IETF draft-11, e.g. `"minute";q=600;w=60, "day";q=200000;w=86400`. Authenticated responses. schema: type: string RateLimit: description: >- IETF draft-11, e.g. `"minute";r=12;t=41`. Authenticated responses; `Retry-After` wins. schema: type: string Cache-Control: description: '`no-store` on run, balance and file responses.' schema: type: string x-should-retry: description: '`true` or `false`, mirrors `retryable`. Every error response.' schema: type: string Allow: description: The allowed methods. Every 405. schema: type: string Retry-After: description: >- Delay-seconds, never more than 60: every 429 and 503, 409 `IDEMPOTENCY_IN_PROGRESS`, 402 `INSUFFICIENT_BALANCE` while an auto top-up is expected, and the poll hint on a 202 or a running run. schema: type: string schemas: Problem: type: object properties: type: type: string format: uri title: type: string status: type: integer minimum: -9007199254740991 maximum: 9007199254740991 detail: type: string code: type: string retryable: type: boolean request_id: type: string errors: type: array items: type: object properties: pointer: type: string message: type: string reason: type: string enum: - unknown_field - missing_required - wrong_type - not_in_enum - below_minimum - above_maximum - not_multiple_of - too_short - too_long - too_few_items - too_many_items - pattern_mismatch - invalid_format - no_matching_variant - invalid_combination - control_field - invalid_value - file_too_large - unsupported_media_type - duration_too_long - duration_too_short - resolution_too_low - resolution_too_high - unreachable - file_not_found - content_policy - provider_refused expected: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object propertyNames: type: string additionalProperties: type: - string - number - boolean - 'null' received: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object propertyNames: type: string additionalProperties: type: - string - number - boolean - 'null' allowed: type: array items: type: - string - number - boolean - 'null' required: - pointer - message additionalProperties: false retry_after_seconds: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - type - title - status - detail - code - retryable - request_id additionalProperties: {} securitySchemes: bearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.