---
title: "Get Snapshots"
method: GET
path: "/v1/market-data/snapshot"
tags: ["Instrument Data"]
---

# Get Snapshots

`GET /v1/market-data/snapshot`

## Request

- Base URL: `https://api.clearstreet.com`
- URL: `https://api.clearstreet.com/v1/market-data/snapshot`
- Auth: HTTP bearer

Get market data snapshots for one or more securities.

Three targeting modes, mutually exclusive: `instrument_ids` (1-100 ids),
`underlying_instrument_id` + `expiry` together, which resolves the
underlier's option chain for that expiry and returns a snapshot for every
contract in it (uncapped), or `event_codes` (1-100 event tickers), which
returns a snapshot for every market in those events in any status
(uncapped). Unknown event codes are ignored.

## Query parameters

- `instrument_ids` InstrumentIdOrSymbol[]
- `underlying_instrument_id` string: Instrument identifier: either an instrument UUID or a symbol (symbol for equities, OSI for options). Non-UUID inputs are resolved server-side.
- `expiry` string, date

## Response `200`

Market data snapshots

- object
  - `error` ApiError: A direct mapping of tonic::Status, for use in HTTP responses.
    - `code` integer, required: The error code is used to identify the nature of the error. It corresponds to an HTTP status code.
    - `details` object[]
    - `message` string, required: A human-readable message providing more details about the error.
  - `metadata` ResponseMetadata, required: Metadata for the response. This will always contain a request ID which can be used to identify the request to Clear Street for tracing, and optionally may include pagination data.
    - `next_page_token` string, byte, nullable: Base64URL-encoded pagination token
    - `page_number` integer, nullable: Pagination. Included if this was a GET (list) response
    - `previous_page_token` string, byte, nullable: Base64URL-encoded pagination token
    - `request_id` string, required: A unique ID for this request, generated upon ingestion of the request.
    - `total_items` integer, nullable: Total number of items available (not just in this page).
    - `total_pages` integer, nullable: Total number of pages available.
  - `data` MarketDataSnapshot[], required
    - `cumulative_volume` integer, nullable: Cumulative traded volume reported on the most recent trade, in shares for equities or contracts for options. Absent when no trade is available. Deprecated: use `session.cumulative_volume`, the same value from the same source. When a null/undefined value is observed, it indicates that there is no available data.
    - `greeks` SnapshotGreeks: Theoretical price and Greeks for an options snapshot. All values are **per share**; no contract multiplier is applied.
      - `delta` string, required: Delta: ∂V/∂S, range \[-1, 1\].
      - `gamma` string, required: Gamma: ∂²V/∂S².
      - `iv` string, required: Implied volatility. Temporarily withheld: always `0`. Do not use this value; it is not a market implied volatility.
      - `rho` string, required: Rho per 1.0 rate point.
      - `theo_price` string, required: Theoretical option price in USD per share.
      - `theta` string, required: Theta per trading day.
      - `timestamp` string, date-time, required: Timestamp when the Greeks were calculated.
      - `vega` string, required: Vega per 1.0 vol point.
    - `instrument_id` string, required: Unique instrument identifier.
    - `last_quote` SnapshotQuote: L1 quote fields for a market data snapshot.
      - `ask` string, nullable: Current best ask. Absent when no ask is available (one-sided quote). When a null/undefined value is observed, it indicates that there is no available data.
      - `ask_size` integer, nullable: Size at the best ask, in shares. When a null/undefined value is observed, it indicates that there is no available data.
      - `ask_timestamp` string, date-time, nullable: Exchange timestamp of the best ask. Absent when the ask side carries no timestamp. When a null/undefined value is observed, it indicates that there is no available data.
      - `ask_venue` string, nullable: ISO 10383 Market Identifier Code (MIC) of the venue currently holding the national best offer (NBBO). Absent when the ask side carries no venue. When a null/undefined value is observed, it indicates that there is no available data.
      - `bid` string, nullable: Current best bid. Absent when no bid is available (one-sided quote). When a null/undefined value is observed, it indicates that there is no available data.
      - `bid_size` integer, nullable: Size at the best bid, in shares. When a null/undefined value is observed, it indicates that there is no available data.
      - `bid_timestamp` string, date-time, nullable: Exchange timestamp of the best bid. Absent when the bid side carries no timestamp. When a null/undefined value is observed, it indicates that there is no available data.
      - `bid_venue` string, nullable: ISO 10383 Market Identifier Code (MIC) of the venue currently holding the national best bid (NBBO). Absent when the bid side carries no venue. When a null/undefined value is observed, it indicates that there is no available data.
      - `midpoint` string, nullable: Midpoint of bid and ask. Absent when either side is missing. When a null/undefined value is observed, it indicates that there is no available data.
    - `last_trade` SnapshotLastTrade: Last-trade fields for a market data snapshot. For index instruments this carries the current index *level* — a computed value, not a trade: `price` is the level and `size` is always `0` (no contract changes hands).
      - `price` string, required: Most recent last-sale eligible trade price. For index instruments, the current index level.
      - `size` integer, required: Share quantity of the most recent last-sale eligible trade. Always `0` for index instruments, whose level is computed rather than traded.
      - `timestamp` string, date-time, nullable: Exchange timestamp of the most recent last-sale eligible trade. For index instruments, the time the index level was computed. Absent when the trade carries no timestamp. When a null/undefined value is observed, it indicates that there is no available data.
      - `venue` string, nullable: ISO 10383 Market Identifier Code (MIC) of the venue where the most recent last-sale eligible trade took place. Absent when the trade carries no venue; index levels are computed rather than traded and have no venue. When a null/undefined value is observed, it indicates that there is no available data.
    - `name` string, nullable: Security name if available. When a null/undefined value is observed, it indicates that there is no available data.
    - `open_interest` integer, nullable: Open interest (outstanding contracts) as of the most recent OPRA Refresh. Populated for options only; absent for equities and indices. When a null/undefined value is observed, it indicates that there is no available data.
    - `session` SnapshotSession, required: Session-level pricing and OHLV metrics for a market data snapshot. Always present on the snapshot row; every field here is independently nullable except `ohlv_applicable`.
      - `change` string, nullable: Absolute change from previous close to the most recent last-sale-eligible trade. Absent when either side of the computation is unavailable. When a null/undefined value is observed, it indicates that there is no available data.
      - `change_percent` string, nullable: Percent change from previous close to the most recent last-sale-eligible trade. Absent under the same conditions as `change`. When a null/undefined value is observed, it indicates that there is no available data.
      - `cumulative_volume` integer, nullable: Cumulative traded volume for the current session, in shares for equities or contracts for options. Always reflects the current session, even when `ohlv_date` trails it. Absent when `ohlv_applicable` is `false`, or when no trade is available. When a null/undefined value is observed, it indicates that there is no available data.
      - `high` string, nullable: Session high. When a null/undefined value is observed, it indicates that there is no available data.
      - `low` string, nullable: Session low. When a null/undefined value is observed, it indicates that there is no available data.
      - `ohlv_applicable` boolean, required: `false` only for instrument types with no OHLV by definition (e.g. an index instrument, whose price is a computed level rather than a traded security) -- `open`/`high`/`low`/`ohlv_date`/`cumulative_volume` are then always absent. `true` otherwise, even when those fields simply haven't loaded yet. Always serialized.
      - `ohlv_date` string, date, nullable: Session date the open/high/low values represent, US/Eastern. May trail the current session until the upstream feed rolls. When a null/undefined value is observed, it indicates that there is no available data.
      - `open` string, nullable: Session opening price, from the day's OHLC bar. Absent when `ohlv_applicable` is `false`, or when the bar has not loaded yet. When a null/undefined value is observed, it indicates that there is no available data.
      - `previous_close` string, nullable: Previous session close price. Corporate-action-adjusted (stock dividends, cash dividends, and forward/reverse splits) when an adjustment exists for the close date; the raw close otherwise. An adjustment can carry the price beyond 2 decimal places. Absent when no previous close is on record (e.g. an instrument's first session). When a null/undefined value is observed, it indicates that there is no available data.
      - `previous_close_unadjusted` string, nullable: Unadjusted (raw) previous session close. Present only when a corporate-action adjustment exists for the previous close date; when no adjustment exists, `previous_close` is the raw close and this field is omitted. When a null/undefined value is observed, it indicates that there is no available data.
    - `short_sale_restricted` boolean, nullable, required: Whether the SEC Rule 201 short-sale price test is currently restricting short sales in this security, from the trading-status feed. `true` restricts non-exempt short sales at or below the national best bid. `null` means we have no answer, either because no trading status has been seen for this security yet or because Rule 201 does not cover this security type. A `null` is not a statement that short selling is unrestricted, and must not be treated as clear to short. This is the current market condition, not a statement about whether Clear Street will reject your order. It is also distinct from `is_short_prohibited` on the instrument endpoints, which is a standing property of the security rather than a live circuit breaker. When a null/undefined value is observed, it indicates that there is no available data.
    - `symbol` string, required: Display symbol for the security.

## Other responses

- `207`: One or more instrument ids failed to be found
- `400`: Invalid, empty, or over-cap instrument_ids or event_codes
- `404`: All instrument ids failed to be found, or the option chain underlier did not resolve
- `500`: Internal server error
- `503`: Live option snapshot unavailable

## Changes

- **2026-10-30** `7e4b278ca27a`: 1 info
  - added the non-success response with the status `503`
- **2026-10-16** `1bd9eddeffc8`: 1 breaking, 1 warning, 25 info
  - the `allOf[subschema #2]/data/items/session` response's property type changed from no type to `object` for status `200`
  - for the `query` request parameter `instrument_ids`, the type of property `items/` changed from no type to `string`
  - added the new optional `query` request parameter `expiry`
  - added the new optional `query` request parameter `underlying_instrument_id`
  - …23 more
- **2026-07-14** `9632aa50482b`: 1 warning
  - for the `query` request parameter `instrument_ids`, the type of property `items/` changed from `string` to no type, and format from `uuid` to no format
- **2026-07-14** `6ffc79452bbe`: 1 warning
  - for the `query` request parameter `instrument_ids`, the type of property `items/` changed from no type to `string`, and format from no format to `uuid`
- **2026-07-14** `2d8a75e46de7`: 1 warning
  - for the `query` request parameter `instrument_ids`, the type of property `items/` changed from `string` to no type, and format from `uuid` to no format

[Operation history](https://skmtc.dev/clear-street/apis/clear-street-trading-api/changes/v1/market-data/snapshot/get.md)

---

[API](https://skmtc.dev/clear-street/apis/clear-street-trading-api.md) - [All operations](https://skmtc.dev/clear-street/apis/clear-street-trading-api/llms.txt) - [OpenAPI document](https://skmtc.dev/clear-street/apis/clear-street-trading-api/revisions/52e77ea7d731?raw)