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

# Create an Asynchronous Multi-Model Quantura Forecast Job

> Validates the source and immutable configuration, snapshots authorized input data, enqueues a durable worker, and returns HTTP 202. Component-model arrays are not exposed in the standard result.



## OpenAPI

````yaml https://quantura.studio/api/openapi.json post /ensemble-forecasts
openapi: 3.1.0
info:
  title: Quantura Forecast Intelligence API
  version: 1.0.0
  description: >-
    Versioned access to Quantura forecasts, collaborator-aware workspaces,
    screeners, datasets, and provenance metadata.
  contact:
    name: Quantura
    url: https://quantura.studio/contact
  license:
    name: Quantura API Terms
    url: https://quantura.studio/terms
servers:
  - url: https://quantura.studio/api/v1
security:
  - bearerAuth: []
tags:
  - name: Access
    description: Identity, token scopes, plans, and effective workspace access.
  - name: Workspaces
    description: Resources are authorized against current membership on every request.
  - name: Uploaded CSVs
    description: Workspace-isolated CSV metadata, organization, and authorized exports.
  - name: Datasets
    description: Licensing-aware catalog and schema metadata.
  - name: Forecasts
    description: Prospective forecasts and immutable probability trajectories.
  - name: Ensemble Forecasts
    description: >-
      Asynchronous probabilistic time-series ensemble jobs and reproducible
      presets.
  - name: Backtests
    description: >-
      Asynchronous point-in-time ensemble-quantile simulations and versioned
      strategy exports; never live order execution.
paths:
  /ensemble-forecasts:
    post:
      tags:
        - Ensemble Forecasts
      summary: Create an Asynchronous Multi-Model Quantura Forecast Job
      description: >-
        Validates the source and immutable configuration, snapshots authorized
        input data, enqueues a durable worker, and returns HTTP 202.
        Component-model arrays are not exposed in the standard result.
      operationId: createEnsembleForecast
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            maxLength: 180
          description: >-
            Replays the same normalized request without launching duplicate
            compute.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnsembleForecastRequest'
      responses:
        '202':
          description: Forecast job queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnsembleForecastEnvelope'
              example:
                data:
                  forecast_id: ens_01JEXAMPLE7M6N
                  status: queued
                  progress:
                    completed_models: 0
                    total_models: 4
                    current_model: null
                  status_url: /api/v1/ensemble-forecasts/ens_01JEXAMPLE7M6N
                  result_url: /api/v1/ensemble-forecasts/ens_01JEXAMPLE7M6N
                meta:
                  api_version: v1
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                      - request_id
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      request_id:
                        type: string
                        format: uuid
        '403':
          description: Scope, plan, or workspace authorization denied
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                      - request_id
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      request_id:
                        type: string
                        format: uuid
        '422':
          description: >-
            Unsupported model, quantile, horizon, dataset, or transform
            configuration.
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                      - request_id
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      request_id:
                        type: string
                        format: uuid
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                      - request_id
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      request_id:
                        type: string
                        format: uuid
components:
  schemas:
    EnsembleForecastRequest:
      unevaluatedProperties: false
      allOf:
        - $ref: '#/components/schemas/EnsembleConfiguration'
        - type: object
          required:
            - source
          properties:
            workspace_id:
              type: string
            analytics_context:
              type: object
              description: >-
                Optional consented website telemetry; sanitized separately from
                model configuration and excluded from cache identity. Invalid or
                unavailable telemetry does not block forecasting.
              properties:
                analytics_consent:
                  const: granted
                client_id:
                  type: string
                session_id:
                  type: integer
                consent_at:
                  type: string
                  format: date-time
            history_lag_minutes:
              type: integer
              minimum: 0
              default: 0
              description: >-
                Input cutoff before request time, in minutes (hours × 60; days ×
                1440). Select up to 500 observations BEFORE cutoff. Source
                retention still applies. No fixed 90-day cutoff-age cap: 120
                days is 172800 minutes; 180 days is 259200 minutes. Availability
                depends on provider retention. Positive values create a
                historical replay, not a previously published forecast. Later
                observations are separate overlays.
            toto_variant:
              type: string
              enum:
                - 4m
                - 22m
                - 313m
                - 1b
                - 2.5b
              default: 4m
              description: >-
                Approved Toto size, smallest to largest. Only relevant when Toto
                is enabled. The server pins the checkpoint and revision,
                including in the cache identity; clients cannot submit arbitrary
                model repositories. All sizes require at least 32 observed
                values.
            history_cutoff_at:
              type: string
              format: date-time
              description: >-
                Optional past absolute cutoff with timezone offset (ISO 8601),
                subject to available source history. Cannot be combined with a
                positive history_lag_minutes. Browser calendar values convert
                from the user's device timezone to UTC.
            prediction_end_at:
              type: string
              format: date-time
              description: >-
                Optional absolute end date/time. After input materialization,
                the server derives the number of forecast bars only for
                completed future interval boundaries through this time (never
                rounded past the requested end), still subject to 512 and
                model-specific limits. NYSE daily forecasts use real exchange
                sessions in the selected calendar window. Overrides
                prediction_length.
            source:
              oneOf:
                - type: object
                  required:
                    - type
                    - symbol
                  properties:
                    type:
                      const: ticker
                    symbol:
                      type: string
                    provider:
                      type: string
                      enum:
                        - auto
                        - alpaca
                        - yahoo
                        - dukascopy
                    price_side:
                      type: string
                      enum:
                        - bid
                        - ask
                      default: bid
                      description: >-
                        Dukascopy quote side, persisted for refresh and
                        observations.
                    start:
                      type: string
                      format: date
                    limit:
                      type: integer
                      minimum: 2
                      maximum: 10000
                      default: 500
                      description: >-
                        Maximum latest valid observations before cutoff. Model
                        minimum history requirements still apply.
                    frequency:
                      type: string
                      enum:
                        - 1min
                        - 5min
                        - 15min
                        - 30min
                        - 1h
                        - 4h
                        - 1D
                        - 1W-MON
                        - 1MS
                        - 1Min
                        - 5Min
                        - 15Min
                        - 30Min
                        - 1Hour
                        - 4Hour
                        - 1Day
                        - 1Week
                        - 1Month
                        - 1m
                        - 5m
                        - 15m
                        - 30m
                        - 1w
                      default: 1Day
                      description: >-
                        Only completed observations. Weekly/monthly closes
                        aggregate real daily bars on Monday UTC / first-of-month
                        UTC boundaries. Calendar months are never approximated
                        as 30 days.
                    field:
                      type: string
                      enum:
                        - open
                        - high
                        - low
                        - close
                        - volume
                    adjustment:
                      type: string
                      enum:
                        - raw
                        - split
                        - dividend
                        - spin-off
                        - all
                      default: raw
                      description: >-
                        Provider price adjustment. Yahoo uses its adjusted-close
                        factor for non-raw requests; it does not distinguish
                        adjustment event types.
                    session:
                      type: string
                      enum:
                        - regular
                        - extended
                      default: regular
                    feed:
                      type: string
                      enum:
                        - iex
                        - sip
                        - boats
                        - otc
                        - yahoo
                      description: >-
                        Alpaca defaults to iex; other feeds require provider
                        entitlement. Yahoo always uses its own feed. The
                        selected basis is persisted for overlays and refreshes.
                - type: object
                  additionalProperties: false
                  required:
                    - type
                    - provider
                    - symbol
                    - contract_id
                  properties:
                    type:
                      const: prediction_market
                    provider:
                      type: string
                      enum:
                        - polymarket_us
                        - kalshi
                    symbol:
                      type: string
                      description: >-
                        Provider market slug (Polymarket US) or market ticker
                        (Kalshi).
                    contract_id:
                      type: string
                      description: >-
                        Exact selected side ID from market lookup; verified
                        server-side.
                    limit:
                      type: integer
                      minimum: 2
                      maximum: 500
                      default: 500
                      description: >-
                        Maximum latest genuine observations after phase, cutoff
                        and time-window filtering. Fewer are used if
                        unavailable; missing bars are never filled. Model
                        minimums apply.
                    frequency:
                      type: string
                      enum:
                        - 1min
                        - 5min
                        - 15min
                        - 30min
                        - 1h
                        - 4h
                        - 1D
                        - 1W-MON
                        - 1MS
                        - 1Min
                        - 5Min
                        - 15Min
                        - 30Min
                        - 1Hour
                        - 4Hour
                        - 1Day
                        - 1Week
                        - 1Month
                        - 1m
                        - 5m
                        - 15m
                        - 30m
                        - 1w
                      default: 1min
                    history_phase:
                      type: string
                      enum:
                        - auto
                        - both
                        - pregame
                        - in_game
                      default: both
                      description: >-
                        The website defaults to auto: pregame plus in-game
                        before 32 elapsed game minutes, then in-game only,
                        evaluated at the input cutoff. Missing event start keeps
                        auto on both; explicit phase-specific requests require a
                        verified start. Existing API clients retain both when
                        omitted.
                    history_lookback_minutes:
                      type: integer
                      minimum: 0
                      maximum: 129600
                      default: 0
                      description: >-
                        0 imposes no extra time restriction; positive values
                        restrict elapsed history before cutoff. For pregame, the
                        window ends at the earlier of cutoff and game start.
                        source.limit then selects the latest N genuine
                        observations.
                - type: object
                  required:
                    - type
                    - dataset_id
                    - timestamp_column
                    - target_column
                  properties:
                    type:
                      const: workspace_dataset
                    dataset_id:
                      type: string
                    timestamp_column:
                      type: string
                    target_column:
                      type: string
                    frequency:
                      type: string
                    timezone:
                      type: string
                - type: object
                  required:
                    - type
                    - rows
                  properties:
                    type:
                      const: series
                    rows:
                      type: array
                      maxItems: 10000
                      items:
                        type: object
                    timestamp_column:
                      type: string
                    target_column:
                      type: string
                    frequency:
                      type: string
                    timezone:
                      type: string
                - type: object
                  additionalProperties: false
                  required:
                    - type
                    - symbol
                  properties:
                    type:
                      const: kalshi_perp
                    symbol:
                      type: string
                      pattern: ^KX[A-Z0-9]{1,36}PERP$
                    frequency:
                      enum:
                        - 1min
                        - 5min
                        - 15min
                        - 30min
                        - 1h
                        - 4h
                        - 1D
                        - 1W-MON
                        - 1MS
                      default: 1h
                    limit:
                      type: integer
                      minimum: 2
                      maximum: 500
                      default: 500
                  description: >-
                    Kalshi perpetual forecast on normalized
                    USD-per-underlying-unit trade closes. Set
                    horizon_mode=frequency_periods and calendar=NONE; price
                    transforms auto/log/none, never logit. Source, units and
                    contract scaling are resolved by the server.
            analysis_mode:
              type: string
              enum:
                - forecast
              default: forecast
              description: >-
                New jobs provide forecast quantiles without buy/sell
                classifications. Historical saved jobs remain readable.
    EnsembleForecastEnvelope:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: object
          required:
            - forecast_id
            - status
          properties:
            forecast_id:
              type: string
            status:
              type: string
              enum:
                - queued
                - running
                - completed
                - failed
            progress:
              type:
                - object
                - 'null'
            predictions:
              type: array
              items:
                $ref: '#/components/schemas/EnsemblePrediction'
            historical_validation:
              $ref: '#/components/schemas/HistoricalForecastValidation'
            effective_weights_by_quantile:
              type: object
            status_url:
              type: string
            result_url:
              type: string
        meta:
          type: object
          properties:
            api_version:
              const: v1
    EnsembleConfiguration:
      type: object
      required:
        - prediction_length
        - horizon_mode
        - quantiles
        - models
      properties:
        prediction_length:
          type: integer
          minimum: 1
          maximum: 512
          default: 30
        horizon_mode:
          type: string
          enum:
            - trading_sessions
            - calendar_days
            - frequency_periods
        quantiles:
          type: array
          minItems: 1
          maxItems: 21
          uniqueItems: true
          items:
            type: number
            exclusiveMinimum: 0
            exclusiveMaximum: 1
        transform:
          type: string
          enum:
            - auto
            - log
            - none
            - logit
          default: auto
          description: >-
            Prediction-market sources enforce bounded logit forecasting, with
            epsilon 1e-6 at transform boundaries.
        context_length:
          type:
            - integer
            - 'null'
          minimum: 40
          maximum: 16384
          default: 512
        model_failure_policy:
          type: string
          enum:
            - fail
            - renormalize
          default: fail
        frequency:
          type: string
          default: 1D
          description: >-
            Canonical market intervals: 1min, 5min, 15min, 30min, 1h, 4h, 1D,
            1W-MON, 1MS. source.frequency determines market input bars;
            series/workspace datasets can also use validated pandas offsets.
        calendar:
          type: string
          default: NYSE
        models:
          type: object
          additionalProperties: false
          properties:
            prophet:
              $ref: '#/components/schemas/ModelSelection'
            toto:
              $ref: '#/components/schemas/ModelSelection'
            granite:
              $ref: '#/components/schemas/ModelSelection'
            chronos:
              $ref: '#/components/schemas/ModelSelection'
            timesfm:
              $ref: '#/components/schemas/ModelSelection'
    EnsemblePrediction:
      type: object
      required:
        - timestamp
        - quantiles
      properties:
        timestamp:
          type: string
          format: date-time
        quantiles:
          type: object
          additionalProperties:
            type: number
          description: Canonical decimal quantile string to final ensemble value.
    HistoricalForecastValidation:
      type: object
      required:
        - policy
        - method
        - status
        - metrics
      description: >-
        Optional legacy historical-validation summary preserved on older
        results. New forecast requests and reproductions do not run a holdout or
        delay completion for metrics. These legacy scores describe a separate
        forecast, not the requested future predictions.
      properties:
        policy:
          const: chronological_holdout_v1
        method:
          const: chronological_holdout
        status:
          type: string
          enum:
            - completed
            - insufficient_history
            - no_matching_outcomes
            - failed
        training_rows:
          type: integer
          minimum: 2
        holdout_rows:
          type: integer
          minimum: 1
          maximum: 30
        training_end_at:
          type: string
          format: date-time
        validation_start_at:
          type: string
          format: date-time
        validation_end_at:
          type: string
          format: date-time
        requested_models:
          type: array
          items:
            type: string
        effective_weights_by_quantile:
          type: object
        metrics:
          type:
            - object
            - 'null'
          properties:
            count:
              type: integer
              minimum: 0
            point_count:
              type: integer
              minimum: 0
            mae:
              type:
                - number
                - 'null'
              minimum: 0
            rmse:
              type:
                - number
                - 'null'
              minimum: 0
            smape:
              type:
                - number
                - 'null'
              minimum: 0
              maximum: 2
              description: >-
                Ratio, not percent; the UI multiplies by 100. Zero/zero
                contributes zero.
            average_wql:
              type:
                - number
                - 'null'
              minimum: 0
              description: >-
                Mean twice-pinball loss divided by total absolute actual values;
                null for all-zero actuals.
      example:
        policy: chronological_holdout_v1
        method: chronological_holdout
        status: completed
        training_rows: 493
        holdout_rows: 7
        training_end_at: '2026-09-08T20:00:00Z'
        validation_start_at: '2026-09-09T20:00:00Z'
        validation_end_at: '2026-09-17T20:00:00Z'
        metrics:
          count: 7
          point_count: 7
          mae: 1.25
          rmse: 1.6
          smape: 0.012
          average_wql: 0.018
    ModelSelection:
      type: object
      additionalProperties: false
      required:
        - enabled
        - weight
      properties:
        enabled:
          type: boolean
        weight:
          type: number
          minimum: 0
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Quantura API key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.