> ## 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.

# Download market history

> One endpoint for stocks (auto/alpaca), Dukascopy instruments, Kalshi perpetuals (kalshi_perps), Kalshi/Polymarket US event contracts, Gemini spot markets and prediction-contract snapshots, Treasury Fiscal Data, World Bank Data360 and BigQuery public time series. For Gemini or economic datasets, pass a structured source object matching the forecast source (type=gemini_spot or economic_series). Inspect economic dimensions with Search describe. BigQuery requires a signed-in identity, a dry run and a 100 MiB billed-byte cap. Economic rows use timestamp/target and native reporting frequency; revised data is not a historical vintage. Gemini supplies a bounded recent candle window. Prediction-contract snapshots use JSON and cannot currently be forecast without a verified historical series. Use source and symbol for instruments; use source, contracts, start and end for events. Perpetual prices are normalized to USD per underlying unit using provider contract scaling. No missing bars are filled. Perpetuals allow at most 5000 rows and 20000 intervals per date range. Follow Dukascopy next_cursor with page_mode=true and identical settings. CSV export requires a completed unpaged range. Provider licensing and available history still apply. Set mode=canvas with format=csv for a SageMaker Canvas import file, or format=json to preview identical columns. Instrument/Gemini spot exports use candle close; economic exports use the selected numeric value. Event exports preserve separate item IDs for each side and use the selected target field. Canvas still validates cadence, sample count and supported model intervals (4-hour observations require resampling in Canvas). Prediction-contract snapshots without history cannot be exported as Canvas time series.



## OpenAPI

````yaml /docs/api/openapi.json post /v1/market-data/history
openapi: 3.1.0
info:
  title: Quantura API
  version: 1.0.0
  description: >-
    Search markets and public datasets, download historical observations, create
    forecasts and inspect screener quantiles.
  contact:
    name: Quantura
    url: https://quantura.studio/contact
  license:
    name: Quantura API Terms
    url: https://quantura.studio/terms
servers:
  - url: https://quantura.studio/api
security:
  - bearerAuth: []
  - clerkOAuth:
      - openid
      - profile
      - email
tags:
  - name: Access
  - name: Forecast
  - name: Screener
  - name: Search
  - name: Download
  - name: Scout
paths:
  /v1/market-data/history:
    servers:
      - url: https://quantura.studio/api
    post:
      tags:
        - Download
      summary: Download market history
      description: >-
        One endpoint for stocks (auto/alpaca), Dukascopy instruments, Kalshi
        perpetuals (kalshi_perps), Kalshi/Polymarket US event contracts, Gemini
        spot markets and prediction-contract snapshots, Treasury Fiscal Data,
        World Bank Data360 and BigQuery public time series. For Gemini or
        economic datasets, pass a structured source object matching the forecast
        source (type=gemini_spot or economic_series). Inspect economic
        dimensions with Search describe. BigQuery requires a signed-in identity,
        a dry run and a 100 MiB billed-byte cap. Economic rows use
        timestamp/target and native reporting frequency; revised data is not a
        historical vintage. Gemini supplies a bounded recent candle window.
        Prediction-contract snapshots use JSON and cannot currently be forecast
        without a verified historical series. Use source and symbol for
        instruments; use source, contracts, start and end for events. Perpetual
        prices are normalized to USD per underlying unit using provider contract
        scaling. No missing bars are filled. Perpetuals allow at most 5000 rows
        and 20000 intervals per date range. Follow Dukascopy next_cursor with
        page_mode=true and identical settings. CSV export requires a completed
        unpaged range. Provider licensing and available history still apply. Set
        mode=canvas with format=csv for a SageMaker Canvas import file, or
        format=json to preview identical columns. Instrument/Gemini spot exports
        use candle close; economic exports use the selected numeric value. Event
        exports preserve separate item IDs for each side and use the selected
        target field. Canvas still validates cadence, sample count and supported
        model intervals (4-hour observations require resampling in Canvas).
        Prediction-contract snapshots without history cannot be exported as
        Canvas time series.
      operationId: downloadQuanturaMarketHistory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required:
                    - symbol
                  properties:
                    symbol:
                      type: string
                    contractSymbol:
                      type: string
                    source:
                      type: string
                      enum:
                        - auto
                        - alpaca
                        - dukascopy
                        - kalshi_perps
                      default: auto
                    price_side:
                      type: string
                      enum:
                        - bid
                        - ask
                      default: bid
                    page_mode:
                      type: boolean
                      description: >-
                        Dukascopy: retrieve bounded candle file pages; follow
                        next_cursor using the same settings.
                    cursor:
                      type: string
                    start:
                      type: string
                      format: date-time
                    end:
                      type: string
                      format: date-time
                    timeframe:
                      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
                    limit:
                      type: integer
                      minimum: 1
                      maximum: 50000
                      description: >-
                        Kalshi perpetuals: 1–5000; stocks/Dukascopy: 500, 1000,
                        1500, 2000, 50000 (default 2000).
                    adjustment:
                      type: string
                      enum:
                        - raw
                        - split
                        - all
                    session:
                      type: string
                      enum:
                        - regular
                        - extended
                    format:
                      type: string
                      enum:
                        - json
                        - csv
                    mode:
                      type: string
                      enum:
                        - normalized
                        - raw
                        - canvas
                      default: normalized
                      description: >-
                        canvas returns item_id, timestamp (UTC), and numeric
                        target columns for SageMaker Canvas. Candle close is the
                        target; economic series retain their selected value. Raw
                        provider fields are available only for event contracts.
                        Missing observations are not filled.
                    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
                      description: >-
                        Alias for timeframe. Perpetuals support the same
                        completed-bar frequencies.
                - type: object
                  required:
                    - source
                    - contracts
                    - start
                    - end
                  properties:
                    source:
                      type: string
                      enum:
                        - kalshi
                        - polymarket_us
                    contracts:
                      type: array
                      minItems: 1
                      maxItems: 25
                      items:
                        type: object
                        required:
                          - source
                          - eventId
                          - marketId
                          - contractId
                          - providerSymbol
                          - side
                        properties:
                          source:
                            type: string
                          eventId:
                            type: string
                          marketId:
                            type: string
                          contractId:
                            type: string
                          providerSymbol:
                            type: string
                          side:
                            type: string
                            enum:
                              - 'yes'
                              - 'no'
                              - long
                              - short
                    start:
                      type: string
                      format: date-time
                    end:
                      type: string
                      format: date-time
                    frequency:
                      type: string
                      enum:
                        - raw
                        - 1m
                        - 5m
                        - 15m
                        - 30m
                        - 1h
                        - 4h
                        - 1d
                        - 1w
                        - 1month
                        - final
                    history_phase:
                      type: string
                      enum:
                        - auto
                        - both
                        - pregame
                        - in_game
                    mode:
                      type: string
                      enum:
                        - normalized
                        - raw
                        - canvas
                    target:
                      type: string
                      enum:
                        - price
                        - bid
                        - ask
                        - midpoint
                    missing:
                      type: string
                      enum:
                        - leave
                        - drop
                        - forward_fill
                    format:
                      type: string
                      enum:
                        - json
                        - csv
                      default: csv
                - type: object
                  additionalProperties: false
                  required:
                    - source
                  properties:
                    source:
                      oneOf:
                        - $ref: '#/components/schemas/EconomicSeriesSource'
                        - $ref: '#/components/schemas/GeminiSpotSource'
                        - $ref: '#/components/schemas/GeminiPredictionSource'
                    format:
                      type: string
                      enum:
                        - json
                        - csv
                      default: json
                    mode:
                      type: string
                      enum:
                        - normalized
                        - raw
                        - canvas
                      default: normalized
                      description: >-
                        canvas returns item_id, timestamp (UTC), and numeric
                        target columns for SageMaker Canvas. Candle close is the
                        target; economic series retain their selected value. Raw
                        provider fields are available only for event contracts.
                        Missing observations are not filled.
            examples:
              gemini:
                value:
                  source:
                    type: gemini_spot
                    symbol: BTCUSD
                    frequency: 1h
                    limit: 500
                  format: json
              treasury:
                value:
                  source:
                    type: economic_series
                    provider: fiscaldata
                    series_id: debt_to_penny
                    value_field: tot_pub_debt_out_amt
                    limit: 500
                  format: json
              stock:
                value:
                  source: alpaca
                  symbol: AAPL
                  timeframe: 1Day
                  limit: 500
                  format: json
              perpetual:
                value:
                  source: kalshi_perps
                  symbol: KXBTCPERP
                  frequency: 1h
                  limit: 500
                  format: json
              dukascopy:
                value:
                  source: dukascopy
                  symbol: XAUUSD
                  timeframe: 1h
                  limit: 500
                  price_side: bid
                  format: json
              canvas:
                summary: SageMaker Canvas-ready stock history
                value:
                  source: alpaca
                  symbol: AAPL
                  timeframe: 1Day
                  limit: 500
                  adjustment: split
                  mode: canvas
                  format: csv
      responses:
        '200':
          description: Successful response (illustrative example)
          content:
            application/json:
              schema:
                type: object
              example:
                ok: true
                count: 0
                rows: []
            text/csv:
              schema:
                type: string
              examples:
                standard:
                  value: "timestamp,close\r\n2026-09-18T04:00:00Z,101"
                canvas:
                  value: "item_id,timestamp,target\r\n\"alpaca:AAPL\",2026-09-18T04:00:00Z,101"
        '404':
          description: Invalid request or provider unavailable
          content:
            application/json:
              schema:
                type: object
              example:
                ok: false
                error: event_query_invalid
                message: Choose a provider event and a valid continuation cursor.
        '422':
          description: Invalid request or provider unavailable
          content:
            application/json:
              schema:
                type: object
              example:
                ok: false
                error: event_query_invalid
                message: Choose a provider event and a valid continuation cursor.
        '429':
          description: Invalid request or provider unavailable
          content:
            application/json:
              schema:
                type: object
              example:
                ok: false
                error: event_query_invalid
                message: Choose a provider event and a valid continuation cursor.
        '502':
          description: Invalid request or provider unavailable
          content:
            application/json:
              schema:
                type: object
              example:
                ok: false
                error: event_query_invalid
                message: Choose a provider event and a valid continuation cursor.
        '503':
          description: Invalid request or provider unavailable
          content:
            application/json:
              schema:
                type: object
              example:
                ok: false
                error: event_query_invalid
                message: Choose a provider event and a valid continuation cursor.
      security:
        - bearerAuth: []
        - clerkOAuth:
            - openid
            - profile
            - email
components:
  schemas:
    EconomicSeriesSource:
      type: object
      additionalProperties: false
      required:
        - type
        - provider
      properties:
        type:
          const: economic_series
        provider:
          type: string
          enum:
            - fiscaldata
            - worldbank_data360
            - bigquery
        series_id:
          type: string
          enum:
            - debt_to_penny
            - rates_of_exchange
            - avg_interest_rates
            - operating_cash_balance
        table_id:
          type: string
        time_field:
          type: string
        aggregation:
          type: string
          enum:
            - none
            - avg
            - sum
            - min
            - max
        frequency:
          type: string
          enum:
            - 1h
            - 1D
            - 1W-MON
            - 1MS
        value_field:
          type: string
        dataset_id:
          type: string
        indicator_id:
          type: string
        ref_area:
          type: string
        dimensions:
          type: object
          additionalProperties:
            type: string
        limit:
          type: integer
          minimum: 2
          maximum: 50000
          default: 500
        start:
          type: string
        end:
          type: string
      oneOf:
        - properties:
            provider:
              const: fiscaldata
          required:
            - series_id
        - properties:
            provider:
              const: worldbank_data360
          required:
            - dataset_id
            - indicator_id
        - properties:
            provider:
              const: bigquery
          required:
            - dataset_id
            - table_id
      description: >-
        Select one series and one value for every required dimension. Reporting
        periods are daily, month-end, quarter-end, or year-end. Current revised
        data is not a point-in-time vintage. BigQuery history additionally
        requires time_field and value_field, uses only bigquery-public-data,
        exact parameterized filters, a dry run and a 100 MiB billed-byte cap.
    GeminiSpotSource:
      type: object
      additionalProperties: false
      required:
        - type
        - symbol
      properties:
        type:
          const: gemini_spot
        symbol:
          type: string
        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
        limit:
          type: integer
          minimum: 2
          maximum: 50000
          default: 500
        start:
          type: string
        end:
          type: string
      description: >-
        Verified Gemini exchange spot symbol. Only completed candles returned by
        the provider's bounded recent window are available.
    GeminiPredictionSource:
      type: object
      additionalProperties: false
      required:
        - type
        - symbol
        - event_id
        - contract_id
      properties:
        type:
          const: gemini_prediction_contract
        symbol:
          type: string
        event_id:
          type: string
        contract_id:
          type: string
      description: >-
        Provider-verified Gemini prediction contract snapshot. JSON observations
        may be absent. Forecasting requires a verified historical side-specific
        series and is not currently offered.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Clerk personal API key or legacy Quantura key
    clerkOAuth:
      type: oauth2
      description: >-
        Clerk authorization code with PKCE S256. Pass
        resource=https://quantura.studio on authorization and token requests.
        Paid Pro, enterprise or verified administrator API access is required.
      flows:
        authorizationCode:
          authorizationUrl: https://clerk.quantura.studio/oauth/authorize
          tokenUrl: https://clerk.quantura.studio/oauth/token
          refreshUrl: https://clerk.quantura.studio/oauth/token
          scopes:
            openid: Identify the Quantura account
            profile: Resolve the account profile
            email: Verify account email
            offline_access: Refresh access after expiry

````

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