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

# Get price history

> Retrieve recorded bid, ask, midpoint or last-trade prices for selected Rook listing_ids in a UTC time window. Supply start_time, end_time and field; sampling_interval optionally requests a supported sampling cadence.

Items identify the listing, field, price, observation/source times, sampling method and whether a value was carried forward. Gaps remain explicit and missing observations do not become fabricated candles. Follow next_page_token with the same filters and time range to continue the snapshot. For transaction records rather than sampled prices, use /trades.

See the [integration guide](/guides/market-data) for the workflow and interpretation of this response.


## OpenAPI

````yaml GET /price-history
openapi: 3.1.0
info:
  title: Rook API
  version: 0.1.0-design
  description: Markets, settlement relationships, scenarios, payouts and market data.
servers:
  - url: https://api.rook.pm/v1
    description: Proposed API origin; not an assertion these operations are callable.
security:
  - ApiKeyBearer: []
tags:
  - name: Reference data
    description: Events, unified markets and native-ID resolution.
  - name: Families and scenarios
    description: Family scope and versioned scenario columns.
  - name: Relationships and Combos
    description: Related-market discovery, selected-set inference and Combo interpretation.
  - name: Payouts and exposure
    description: Scoped per-unit payouts and stateless portfolio/candidate calculations.
  - name: Market data
    description: Current prices, history, L2 books, prints, statistics and published fees.
  - name: Fair values
    description: Future private customer estimates; not Rook forecasts.
  - name: Coverage and updates
    description: Supported capabilities and incremental semantic changes.
paths:
  /price-history:
    get:
      tags:
        - Market data
      summary: Get price history
      description: >-
        Retrieve recorded bid, ask, midpoint or last-trade prices for selected
        Rook listing_ids in a UTC time window. Supply start_time, end_time and
        field; sampling_interval optionally requests a supported sampling
        cadence.


        Items identify the listing, field, price, observation/source times,
        sampling method and whether a value was carried forward. Gaps remain
        explicit and missing observations do not become fabricated candles.
        Follow next_page_token with the same filters and time range to continue
        the snapshot. For transaction records rather than sampled prices, use
        /trades.
      operationId: listPriceHistory
      parameters:
        - name: listing_ids
          in: query
          required: true
          description: >-
            Rook listing IDs from /markets or /markets:resolve. Select the venue
            and outcome side explicitly; repeat the query parameter for multiple
            listings.
          schema:
            type: array
            items:
              type: string
              description: Opaque text identifier. Preserve its exact value.
              minLength: 1
            minItems: 1
          style: form
          explode: true
          example:
            - lst_pm_fed_dec_2026_cut_yes
        - name: start_time
          in: query
          required: true
          description: >-
            UTC start of the requested observation/execution window. Must
            precede end_time when both are supplied.
          schema:
            type: string
            format: date-time
          example: '2026-10-19T11:58:00Z'
        - name: end_time
          in: query
          required: true
          description: >-
            UTC end of the requested observation/execution window. Must follow
            start_time when both are supplied.
          schema:
            type: string
            format: date-time
          example: '2026-10-19T12:00:00Z'
        - name: field
          in: query
          required: true
          description: >-
            Price observation to retrieve: BID, ASK, MIDPOINT or LAST_TRADE,
            oriented to the selected listing outcome.
          schema:
            type: string
            enum:
              - BID
              - ASK
              - MIDPOINT
              - LAST_TRADE
          example: MIDPOINT
        - name: sampling_interval
          in: query
          required: false
          description: >-
            Supported sampling cadence, such as 1m. The response reports its
            sampling and carry-forward method; consult coverage for available
            intervals.
          schema:
            type: string
          example: 1m
        - name: page_size
          in: query
          required: false
          description: >-
            Requested maximum items; service caps disclosed by coverage.
            Oversize requests fail explicitly.
          schema:
            type: integer
            minimum: 1
            default: 50
        - name: page_token
          in: query
          required: false
          description: >-
            Opaque continuation; reuse the same filters/order. Cursor pins the
            original snapshot.
          schema:
            type: string
        - name: X-Client-Request-Id
          in: header
          required: false
          schema:
            type: string
          description: Caller correlation reference; not an idempotency guarantee.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPriceHistoryResponse'
              example:
                items:
                  - listing_id: lst_pm_fed_dec_2026_cut_yes
                    field: MIDPOINT
                    price: '0.40'
                    quote_currency: USDC
                    observed_at: '2026-10-19T11:58:00Z'
                    source_timestamp: '2026-10-19T11:58:00Z'
                    sampling_method: LAST_OBSERVATION_PER_INTERVAL
                    carried_forward: false
                    status: AVAILABLE
                  - listing_id: lst_pm_fed_dec_2026_cut_yes
                    field: MIDPOINT
                    price: '0.41'
                    quote_currency: USDC
                    observed_at: '2026-10-19T11:59:00Z'
                    source_timestamp: '2026-10-19T11:59:00Z'
                    sampling_method: LAST_OBSERVATION_PER_INTERVAL
                    carried_forward: false
                    status: AVAILABLE
                next_page_token: null
                snapshot_id: snap_rates_20261019_120000
                as_of: '2026-10-19T12:00:00Z'
          headers:
            X-Request-Id:
              description: Server request trace ID.
              schema:
                type: string
                description: Opaque text identifier. Preserve its exact value.
                minLength: 1
components:
  schemas:
    ListPriceHistoryResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/PriceObservation'
        next_page_token:
          anyOf:
            - type: string
            - type: 'null'
        snapshot_id:
          type: string
          description: Opaque text identifier. Preserve its exact value.
          minLength: 1
        as_of:
          type: string
          format: date-time
      required:
        - items
        - next_page_token
        - snapshot_id
        - as_of
      additionalProperties: true
    PriceObservation:
      type: object
      properties:
        listing_id:
          type: string
          minLength: 1
          description: >-
            Rook ID for one outcome listing on one venue; preserves venue
            provenance.
        field:
          type: string
          enum:
            - BID
            - ASK
            - MIDPOINT
            - LAST_TRADE
        price:
          anyOf:
            - $ref: '#/components/schemas/Decimal'
            - type: 'null'
        quote_currency:
          type: string
        observed_at:
          type: string
          format: date-time
        source_timestamp:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        sampling_method:
          type: string
        carried_forward:
          type: boolean
        status:
          type: string
          enum:
            - AVAILABLE
            - MISSING
            - STALE
      required:
        - listing_id
        - field
        - price
        - observed_at
        - source_timestamp
        - sampling_method
        - carried_forward
        - status
      additionalProperties: true
    Decimal:
      type: string
      description: >-
        Exact base-10 value encoded as a string; no exponent or non-finite
        values.
      pattern: ^-?(0|[1-9][0-9]*)(\.[0-9]+)?$
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      description: >-
        Proposed server-to-server API key. No client request HMAC signing scheme
        is specified.

````

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