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

# Get spread history

> Lightweight time series of derived orderbook metrics (best bid/ask, mid price, spread, liquidity depth) without raw bids/asks — ideal for charting. Default limit 20, max 200.



## OpenAPI

````yaml https://api.struct.to/openapi.json get /polymarket/order-book/spread
openapi: 3.1.0
info:
  title: Polymarket API
  description: >-
    RESTful API for querying Polymarket prediction markets data including
    events, markets, traders, holders, and real-time metrics
  license:
    name: ''
  version: 1.0.0
servers:
  - url: https://api.struct.to/v1
security: []
paths:
  /polymarket/order-book/spread:
    get:
      tags:
        - Order Book
      summary: Get spread history
      description: >-
        Lightweight time series of derived orderbook metrics (best bid/ask, mid
        price, spread, liquidity depth) without raw bids/asks — ideal for
        charting. Default limit 20, max 200.
      operationId: get_spread_history
      parameters:
        - name: position_id
          in: query
          description: Token ID (required if condition_id / market_slug not set)
          required: false
          schema:
            type: string
        - name: condition_id
          in: query
          description: >-
            Condition ID — returns spread history for all positions in this
            market
          required: false
          schema:
            type: string
        - name: market_slug
          in: query
          description: Market slug (alternative to condition_id)
          required: false
          schema:
            type: string
        - name: from
          in: query
          description: Start timestamp (Unix milliseconds, inclusive)
          required: false
          schema:
            type: integer
            format: int64
        - name: to
          in: query
          description: End timestamp (Unix milliseconds, inclusive)
          required: false
          schema:
            type: integer
            format: int64
        - name: min_spread
          in: query
          description: Only return rows with spread >= this value
          required: false
          schema:
            type: number
            format: double
        - name: max_spread
          in: query
          description: Only return rows with spread <= this value
          required: false
          schema:
            type: number
            format: double
        - name: min_liquidity
          in: query
          description: Only return rows where total liquidity (bid + ask) >= this value
          required: false
          schema:
            type: number
            format: double
        - name: limit
          in: query
          description: 'Number of results (default: 20, max: 200)'
          required: false
          schema:
            type: integer
            format: int64
        - name: pagination_key
          in: query
          description: Cursor from previous response's pagination.pagination_key
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Spread time series rows, newest first. ts is Unix milliseconds.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: >-
                    One bucket of derived order-book metrics for a position at a
                    point in time.

                    Only summary metrics are returned — the underlying bid/ask
                    ladders are

                    available from the snapshot endpoint.
                  required:
                    - ts
                    - position_id
                    - condition_id
                  properties:
                    ts:
                      type: integer
                      format: int64
                      description: Unix timestamp in seconds.
                    position_id:
                      type: string
                      description: Position ID.
                    condition_id:
                      type: string
                      description: Condition ID.
                    best_bid:
                      type:
                        - number
                        - 'null'
                      format: double
                      description: Best bid.
                    best_ask:
                      type:
                        - number
                        - 'null'
                      format: double
                      description: Best ask.
                    mid_price:
                      type:
                        - number
                        - 'null'
                      format: double
                      description: Mid price.
                    spread:
                      type:
                        - number
                        - 'null'
                      format: double
                      description: Spread.
                    bid_liquidity_usd:
                      type:
                        - number
                        - 'null'
                      format: double
                      description: Bid liquidity in USD.
                    ask_liquidity_usd:
                      type:
                        - number
                        - 'null'
                      format: double
                      description: Ask liquidity in USD.
                    bid_levels:
                      type:
                        - integer
                        - 'null'
                      format: int32
                      description: Bid levels.
                    ask_levels:
                      type:
                        - integer
                        - 'null'
                      format: int32
                      description: Ask levels.
        '400':
          description: Missing or invalid parameters

````