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

# Estimate a run



## OpenAPI

````yaml api-reference/openapi.json POST /v1/estimate
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. Exception (rule 5, ADR 0167): a create whose outcome is still
    unknown after those retries may be sent again with the same key at most 3
    more times, each at least 60 s after the last (up to 8 sends in about 4
    minutes); a keyed replay is answered before the input checks, so these
    resolve in milliseconds once the run exists.

    3. Retry-After is a floor: wait at least that long (add 0–20 % jitter).
    Spiral 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 replays its run for 24 hours;
    after that the same key starts 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 7 days. 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/estimate:
    post:
      tags:
        - Discovery
      summary: 'Price this exact input: the amount a run would hold, without a hold.'
      operationId: estimate
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                provider:
                  type: string
                  minLength: 1
                  description: Provider id.
                model:
                  type: string
                  minLength: 1
                  description: Catalog id.
                input:
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties: {}
                  description: >-
                    The same non-empty `input` object as the run (provider field
                    names; file ids allowed).
              required:
                - provider
                - model
                - input
              additionalProperties: false
      responses:
        '200':
          description: The estimate.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  estimate:
                    anyOf:
                      - type: object
                        properties:
                          amount:
                            type: string
                          amount_micros:
                            type: integer
                            minimum: -9007199254740991
                            maximum: 9007199254740991
                          currency:
                            type: string
                            const: USD
                        required:
                          - amount
                          - amount_micros
                          - currency
                      - type: 'null'
                    description: >-
                      The amount held. Null for an API key Spiral set to the
                      customer price view (ADR 0145), whose answers state no USD
                      amount.
                  customer_price:
                    anyOf:
                      - type: object
                        properties:
                          minor_units:
                            anyOf:
                              - type: integer
                                minimum: -9007199254740991
                                maximum: 9007199254740991
                              - type: 'null'
                            description: >-
                              The amount in the organization's minor units,
                              rounded up; null above 2^53 − 1, which a JSON
                              number cannot state exactly (use `amount`).
                          amount:
                            type: string
                            description: >-
                              `minor_units` in the organization's unit, as an
                              exact decimal.
                          unit:
                            type: string
                        required:
                          - minor_units
                          - amount
                          - unit
                      - type: 'null'
                    description: >-
                      The estimate in the organization's own unit, from its
                      current setting. Set by Spiral for an organization that
                      resells in its own unit with its own markup (ADR 0144);
                      null otherwise. Informational: Spiral charges the
                      organization the USD amount.
                  kind:
                    type: string
                    enum:
                      - exact
                      - maximum
                      - approximate
                  units:
                    type: array
                    items:
                      type: object
                      properties:
                        unit:
                          type: string
                        quantity:
                          type: number
                      required:
                        - unit
                        - quantity
                required:
                  - estimate
                  - customer_price
                  - kind
                  - units
        '400':
          description: 'Problem: INVALID_JSON, INVALID_REQUEST, INVALID_INPUT.'
          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: PROVIDER_DISABLED_BY_ORG, MODEL_DISABLED_BY_ORG,
            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'
        '404':
          description: 'Problem: PROVIDER_NOT_FOUND, MODEL_NOT_FOUND, FILE_NOT_FOUND.'
          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'
        '410':
          description: 'Problem: MODEL_RETIRED.'
          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'
        '413':
          description: 'Problem: PAYLOAD_TOO_LARGE.'
          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'
        '415':
          description: 'Problem: UNSUPPORTED_MEDIA_TYPE.'
          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'
        '422':
          description: >-
            Problem: PRICE_UNAVAILABLE, MODEL_NOT_AVAILABLE,
            INPUT_URL_UNREACHABLE.
          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'
        '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: PROVIDER_PAUSED, MODEL_PAUSED, SCHEMA_UNAVAILABLE,
            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_<ULID>`; 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
    Deprecation:
      description: '`@<unix seconds of deprecated_at>` for a `deprecated` model.'
      schema:
        type: string
    Sunset:
      description: '`<HTTP-date of retires_at>` for a `deprecated` model.'
      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.