---
title: "Get Spread Snapshot"
method: GET
path: "/api/market/spreads"
tags: ["Market Data", "Beta"]
---

# Get Spread Snapshot

`GET /api/market/spreads`

## Request

- Base URL: `https://api.zerogex.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.zerogex.io/api/market/spreads`
- Auth: HTTP bearer

Current quoted-width and liquidity across one symbol's near-dated chain.

``history`` is null unless ``dte_max`` and ``moneyness_band_pct`` match a
scope the daily rollup actually stored — the writers pin one scope
(``SPREAD_STATS_DTE_MAX`` / ``SPREAD_STATS_MONEYNESS_BAND_PCT``), so any
other filter combination measures a population with no history behind it.
The live reading is still served; only the ranking is withheld.  Callers
wanting a ranked reading at another scope want ``/surface``, whose rollup
is stored per scope and per time of day.

**Beta** — contract may change.

## Query parameters

- `symbol` string: Underlying symbol
- `dte_max` integer: Max days to expiration to include
- `moneyness_band_pct` number: Half-width of the strike band around spot, in percent
- `history_days` integer: Trailing sessions to rank today's reading against (0 to skip)

## Response `200`

Successful Response

- SpreadSnapshotResponse
  - `symbol` string, required
  - `spot_price` number, required
  - `timestamp` string, date-time, required
  - `session_date` string, date, required
  - `basis` string
  - `disclosure` string
  - `scope` SpreadScope, required: The population measured. Two readings are only comparable if these match.
    - `dte_max` integer, required
    - `moneyness_band_pct` number, required
    - `strike_low` number, required
    - `strike_high` number, required
    - `contract_count` integer, required
  - `calls` SpreadAggregateModel, required: One population's quote quality. Widths are null when nothing is quoted.
    - `contract_count` integer, required
    - `tradable_count` integer, required
    - `two_sided_pct` number, required
    - `zero_bid_pct` number, required
    - `crossed_or_locked_pct` number, required
    - `no_quote_pct` number, required
    - `median_spread` number, nullable
    - `median_relative_spread_pct` number, nullable
    - `p90_relative_spread_pct` number, nullable
    - `median_spread_bps_underlying` number, nullable
    - `p90_spread_bps_underlying` number, nullable
    - `total_open_interest` integer
    - `total_volume` integer
  - `puts` SpreadAggregateModel, required: One population's quote quality. Widths are null when nothing is quoted.
    - `contract_count` integer, required
    - `tradable_count` integer, required
    - `two_sided_pct` number, required
    - `zero_bid_pct` number, required
    - `crossed_or_locked_pct` number, required
    - `no_quote_pct` number, required
    - `median_spread` number, nullable
    - `median_relative_spread_pct` number, nullable
    - `p90_relative_spread_pct` number, nullable
    - `median_spread_bps_underlying` number, nullable
    - `p90_spread_bps_underlying` number, nullable
    - `total_open_interest` integer
    - `total_volume` integer
  - `all` SpreadAggregateModel, required: One population's quote quality. Widths are null when nothing is quoted.
    - `contract_count` integer, required
    - `tradable_count` integer, required
    - `two_sided_pct` number, required
    - `zero_bid_pct` number, required
    - `crossed_or_locked_pct` number, required
    - `no_quote_pct` number, required
    - `median_spread` number, nullable
    - `median_relative_spread_pct` number, nullable
    - `p90_relative_spread_pct` number, nullable
    - `median_spread_bps_underlying` number, nullable
    - `p90_spread_bps_underlying` number, nullable
    - `total_open_interest` integer
    - `total_volume` integer
  - `put_call_width_ratio` number, nullable
  - `history` HistoryContext: Where today's reading sits in the symbol's own trailing history. Percentiles are null — not 50, not 0 — when the rollup has too little history to rank against. "No comparison available" and "an ordinary day" must never render identically.
    - `sessions` integer, required
    - `calls_percentile` number, nullable
    - `puts_percentile` number, nullable
    - `all_percentile` number, nullable
    - `puts_median_over_window` number, nullable
    - `calls_median_over_window` number, nullable
    - `puts_vs_window_ratio` number, nullable
  - `calls_by_moneyness` MoneynessBucket[], required
    - `contract_count` integer, required
    - `tradable_count` integer, required
    - `two_sided_pct` number, required
    - `zero_bid_pct` number, required
    - `crossed_or_locked_pct` number, required
    - `no_quote_pct` number, required
    - `median_spread` number, nullable
    - `median_relative_spread_pct` number, nullable
    - `p90_relative_spread_pct` number, nullable
    - `median_spread_bps_underlying` number, nullable
    - `p90_spread_bps_underlying` number, nullable
    - `total_open_interest` integer
    - `total_volume` integer
    - `moneyness_low_pct` number, required
    - `moneyness_high_pct` number, required
    - `label` string, required
  - `puts_by_moneyness` MoneynessBucket[], required
    - `contract_count` integer, required
    - `tradable_count` integer, required
    - `two_sided_pct` number, required
    - `zero_bid_pct` number, required
    - `crossed_or_locked_pct` number, required
    - `no_quote_pct` number, required
    - `median_spread` number, nullable
    - `median_relative_spread_pct` number, nullable
    - `p90_relative_spread_pct` number, nullable
    - `median_spread_bps_underlying` number, nullable
    - `p90_spread_bps_underlying` number, nullable
    - `total_open_interest` integer
    - `total_volume` integer
    - `moneyness_low_pct` number, required
    - `moneyness_high_pct` number, required
    - `label` string, required
  - `by_expiration` SrcApiRoutersSpreadLiquidityExpirationSlice[], required
    - `expiration` string, date, required
    - `dte` integer, required
    - `calls` SpreadAggregateModel, required: One population's quote quality. Widths are null when nothing is quoted.
      - `contract_count` integer, required
      - `tradable_count` integer, required
      - `two_sided_pct` number, required
      - `zero_bid_pct` number, required
      - `crossed_or_locked_pct` number, required
      - `no_quote_pct` number, required
      - `median_spread` number, nullable
      - `median_relative_spread_pct` number, nullable
      - `p90_relative_spread_pct` number, nullable
      - `median_spread_bps_underlying` number, nullable
      - `p90_spread_bps_underlying` number, nullable
      - `total_open_interest` integer
      - `total_volume` integer
    - `puts` SpreadAggregateModel, required: One population's quote quality. Widths are null when nothing is quoted.
      - `contract_count` integer, required
      - `tradable_count` integer, required
      - `two_sided_pct` number, required
      - `zero_bid_pct` number, required
      - `crossed_or_locked_pct` number, required
      - `no_quote_pct` number, required
      - `median_spread` number, nullable
      - `median_relative_spread_pct` number, nullable
      - `p90_relative_spread_pct` number, nullable
      - `median_spread_bps_underlying` number, nullable
      - `p90_spread_bps_underlying` number, nullable
      - `total_open_interest` integer
      - `total_volume` integer
    - `all` SpreadAggregateModel, required: One population's quote quality. Widths are null when nothing is quoted.
      - `contract_count` integer, required
      - `tradable_count` integer, required
      - `two_sided_pct` number, required
      - `zero_bid_pct` number, required
      - `crossed_or_locked_pct` number, required
      - `no_quote_pct` number, required
      - `median_spread` number, nullable
      - `median_relative_spread_pct` number, nullable
      - `p90_relative_spread_pct` number, nullable
      - `median_spread_bps_underlying` number, nullable
      - `p90_spread_bps_underlying` number, nullable
      - `total_open_interest` integer
      - `total_volume` integer

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/zerogex/apis/zerogex-api.md) · [All operations](https://skmtc.dev/zerogex/apis/zerogex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zerogex/apis/zerogex-api/revisions/753b26bf0592?raw)