---
title: "Latest or dated options snapshot for one underlier"
method: GET
path: "/api/v1/options/{symbol}/snapshot"
tags: ["Options"]
---

# Latest or dated options snapshot for one underlier

`GET /api/v1/options/{symbol}/snapshot`

Single underlier options snapshot at the latest cycle (default) or at a specific calendar date via ``?date=YYYY-MM-DD``. Returns the full payload: underlier spot price, ATM IV, per-expiry calls/puts contracts with Greeks (Black-Scholes for the Sugra Finance feed, native for the VIX volatility feed), per-expiry aggregates (volume / OI / put-call ratios / max-pain strike), and precomputed IV surface + term structure. Passing ``?expiry=YYYY-MM-DD`` narrows the response to a single expiry block; an unmatched expiry returns 404. Returns 410 Gone when the symbol is flagged delisted_candidate by the upstream cycle.

## Path parameters

- `symbol` string, required — Underlier ticker.

## Query parameters

- `date` string, nullable — Optional snapshot date (YYYY-MM-DD). Defaults to the latest cycle.
- `expiry` string, nullable — Optional expiry filter (YYYY-MM-DD). Narrows to a single expiry block.

## Response `200`

Latest or dated options snapshot payload.

- EnvelopeOptionsSnapshotPayload
  - `data` OptionsSnapshotPayload, required — Full per-symbol options snapshot payload.
    - `symbol` string, required — Underlier ticker.
    - `name` string, nullable — Underlier name.
    - `type` string, nullable — stock | etf | index | volatility.
    - `asset_class` string, nullable — equity | bond | commodity | currency | volatility.
    - `snapshot_date` string, required — Logical snapshot date (ISO).
    - `snapshot_taken_at` string, nullable — ISO timestamp at upstream fetch time.
    - `manifest_version` string, nullable — Manifest version that produced this snapshot (Unix timestamp).
    - `greeks_source` string, nullable — Snapshot-level Greeks-source enum. Per-contract greeks_source on each row may differ when IV gate triggers.
    - `data_source` string, nullable — Upstream data-source identifier.
    - `license_attribution` string, nullable — License attribution string.
    - `dividend_yield_pct` number, nullable — Dividend yield used in Greeks calc. Null in B6 v1 (zero-dividend B-S).
    - `risk_free_rate_used` number, nullable — Risk-free rate (decimal) used in B-S Greeks at cycle time.
    - `underlier_price` number, nullable — Underlier spot price at snapshot time.
    - `underlier_iv_30d_atm` number, nullable — Computed ATM IV at the first front expiry.
    - `expiries` ExpiryBlock[] — Per-expiry blocks (calls/puts + per-expiry aggregates).
      - `expiration_date` string, required — ISO expiration date.
      - `days_to_expiration` integer, nullable — Calendar days from snapshot_taken_at to expiry.
      - `calls` OptionContract[] — Call contracts.
        - `strike` number, required — Strike price.
        - `last_price` number, nullable — Last traded price; null when no trades.
        - `bid` number, nullable — Best bid; null when no quote.
        - `ask` number, nullable — Best ask; null when no quote.
        - `volume` integer, nullable — Contracts traded since open.
        - `open_interest` integer, nullable — Outstanding open interest.
        - `implied_volatility` number, nullable — Implied volatility as a decimal (0.20 = 20%). Null when upstream missing.
        - `delta` number, nullable — Black-Scholes delta (per 1.00 underlier move). Null when IV gate triggered.
        - `gamma` number, nullable — Black-Scholes gamma. Null when IV gate triggered.
        - `theta` number, nullable — Black-Scholes theta per calendar day. Null when IV gate triggered.
        - `vega` number, nullable — Black-Scholes vega per 1% vol point. Null when IV gate triggered.
        - `rho` number, nullable — Black-Scholes rho per 1% rate point. Null when IV gate triggered.
        - `in_the_money` boolean, nullable — True when strike is in-the-money at snapshot time.
        - `contract_symbol` string, nullable — OCC OSI contract symbol.
        - `last_trade_date` string, nullable — ISO timestamp of last trade; null when no trades since open.
        - `option_type` string, required — C (call) or P (put) per OCC convention.
        - `greeks_source` string, nullable — Per-contract Greeks origin token. Categories: equity IV/Black-Scholes zero-div path, non-equity IV/BS caveat path, exchange-native Greeks (e.g. VIX), or unreliable when the IV gate rejects the input. Wire values are stable tokens (see response payload); do not treat the token string as a brand name.
      - `puts` OptionContract[] — Put contracts.
        - `strike` number, required — Strike price.
        - `last_price` number, nullable — Last traded price; null when no trades.
        - `bid` number, nullable — Best bid; null when no quote.
        - `ask` number, nullable — Best ask; null when no quote.
        - `volume` integer, nullable — Contracts traded since open.
        - `open_interest` integer, nullable — Outstanding open interest.
        - `implied_volatility` number, nullable — Implied volatility as a decimal (0.20 = 20%). Null when upstream missing.
        - `delta` number, nullable — Black-Scholes delta (per 1.00 underlier move). Null when IV gate triggered.
        - `gamma` number, nullable — Black-Scholes gamma. Null when IV gate triggered.
        - `theta` number, nullable — Black-Scholes theta per calendar day. Null when IV gate triggered.
        - `vega` number, nullable — Black-Scholes vega per 1% vol point. Null when IV gate triggered.
        - `rho` number, nullable — Black-Scholes rho per 1% rate point. Null when IV gate triggered.
        - `in_the_money` boolean, nullable — True when strike is in-the-money at snapshot time.
        - `contract_symbol` string, nullable — OCC OSI contract symbol.
        - `last_trade_date` string, nullable — ISO timestamp of last trade; null when no trades since open.
        - `option_type` string, required — C (call) or P (put) per OCC convention.
        - `greeks_source` string, nullable — Per-contract Greeks origin token. Categories: equity IV/Black-Scholes zero-div path, non-equity IV/BS caveat path, exchange-native Greeks (e.g. VIX), or unreliable when the IV gate rejects the input. Wire values are stable tokens (see response payload); do not treat the token string as a brand name.
      - `total_call_volume` integer, nullable — Sum of call volumes.
      - `total_call_oi` integer, nullable — Sum of call open interest.
      - `total_put_volume` integer, nullable — Sum of put volumes.
      - `total_put_oi` integer, nullable — Sum of put open interest.
      - `put_call_ratio_volume` number, nullable — total_put_volume / total_call_volume.
      - `put_call_ratio_oi` number, nullable — total_put_oi / total_call_oi.
      - `max_pain_strike` number, nullable — Strike that minimises sum(|K-S|*OI_S) across the chain.
    - `iv_surface` IvSurfaceRow[], nullable — Precomputed IV surface across fetched expiries.
      - `expiration_date` string, required — ISO expiration date.
      - `days_to_expiration` integer, nullable
      - `atm_iv` number, nullable — At-the-money implied volatility.
      - `atm_strike` number, nullable — Strike used for ATM IV reading.
      - `call_iv_skew` IvSkewRow[] — Call-side skew.
        - `strike` number, required — Strike price.
        - `iv` number, nullable — Implied volatility at this strike.
        - `moneyness` number, nullable — ln(K / S) or similar moneyness measure.
      - `put_iv_skew` IvSkewRow[] — Put-side skew.
        - `strike` number, required — Strike price.
        - `iv` number, nullable — Implied volatility at this strike.
        - `moneyness` number, nullable — ln(K / S) or similar moneyness measure.
    - `term_structure` TermStructureRow[], nullable — Precomputed ATM IV term structure.
      - `days_to_expiration` integer, nullable
      - `atm_iv` number, nullable
  - `meta` SugraMeta, required — Metadata attached to every /api/v1/* response envelope.
    - `endpoint` string, required — Requested endpoint path.
    - `data_time` string, required — ISO 8601 UTC timestamp of the source data, not of the request.
    - `response_time` string, required — ISO 8601 UTC timestamp when this response was produced.
    - `provider` string, required — API name and version.
    - `source` string, nullable — Identifier of the primary upstream source used for this response.
    - `attribution` string, nullable — Human-readable attribution mandated by an upstream source (e.g. a securities regulator or self-regulatory organization). Present only on responses whose source requires the owner and source to be clearly identified. Do not remove or alter it when using the response.
    - `fallback_used` boolean, nullable — True when the primary source failed and a fallback produced the data.
    - `fallback_chain` string[], nullable — Ordered list of sources attempted, in the order they were tried.
    - `cached` boolean, nullable — True when this response was served from the internal cache.
    - `stale` boolean, nullable — True when the cached response was returned after the upstream rate-limited or errored. Clients can use this to detect degraded data.

## Other responses

- `401` — Missing or invalid `x-api-key` header.
- `422` — Validation Error
- `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window.
- `503` — Upstream source is temporarily unavailable. Retry after a short delay.

---

[API](https://skmtc.net/sugra/apis/sugra-api.md) · [All operations](https://skmtc.net/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sugra/sugra-api/versions/dcf7427e6897/schema)