GateData.AI
Simple Template · Stock Price Snapshot

Use case 1: Stock Price Snapshot

GET /v1/markets/snapshot with market=us_equity (required). Live TradeFi path returns price/BBO/day stats when configured; expect data_status=partial when book size or rolling 24h is unavailable (that is a pass, not a failure). Free-sample keys may limit tickers.

Use this template when
  • Need live equity last price / day stats on the shared MarketOK schema
  • Prototype snapshot clients that also work for crypto with market=crypto
  • Reuse the same path / fields as Docs API Reference
Audience: US equity research, quants, research tooling
Output previewStatic sample · not live
AAPL · us_equitysession_change_pct +0.33
$311.97
data_status
partial
volume_24h
day_volume 1
request_id
—
Static fixture from API unit tests · do not invent listing/asset ids · not live
Live US equity may still return metadata.data_status=no_data. Verify Key via BTC crypto snapshot.

Sign in to load a live response. Static sample is shown until then.

Run in Playground Try in MCP Playground Create API Key API Reference

API / MCP

The same template supports REST, Python, and MCP Prompt. Pick the entry you know.

import requests

url = "https://api.gatedata.ai/api/v1/markets/snapshot?query=AAPL&market=us_equity"
r = requests.get(url, headers={"Authorization": "Bearer gd_live_…"}, timeout=10)
r.raise_for_status()
data = r.json()
meta = data.get("metadata") or {}
# Equity TradeFi live: partial is normal (no size / no rolling 24h).
# Prefer day_volume / session_change_*; do not require volume_24h.
print(meta.get("data_status"), data.get("price") or data.get("last_price"),
      data.get("day_volume"), data.get("session_change_amount"), data.get("updated_at"),
      meta.get("limitations"))
print("empty_reason", data.get("empty_reason"), "field_sources", data.get("field_sources"))

Inputs

Changing parameters updates the code samples and request URL. Defaults are one-click runnable for live templates.

GET/api/v1/markets/snapshot?query=AAPL&market=us_equity

Output & interpretation

Static sample responseStatic sample · not live
{
  "data_status": "partial",
  "market": "us_equity",
  "ticker": "AAPL",
  "price": 311.97,
  "last_price": 311.97,
  "session_change_pct": 0.33,
  "day_open": 309,
  "day_high": 311,
  "day_low": 305,
  "day_volume": 1,
  "day_turnover": 2,
  "open_price": 309,
  "high_price": 311,
  "low_price": 305,
  "volume": 1,
  "turnover": 2,
  "volume_ratio": null,
  "bid_price": 313.66,
  "ask_price": 314.29,
  "best_bid": 313.66,
  "best_ask": 314.29,
  "bid_volume": null,
  "ask_volume": null,
  "mid_price": 313.975,
  "spread_bps": 20.065291822597196,
  "market_session": "post_market",
  "snapshot_type": "single_venue",
  "updated_at": "2026-08-05T20:56:00Z",
  "as_of_utc": "2026-08-05T20:56:00Z",
  "venue_quotes": [],
  "field_sources": {
    "price": "live:session",
    "last_price": "live:session",
    "as_of_utc": "live:session",
    "session_change_pct": "live:session",
    "market_session": "live:session",
    "bid_price": "live:orderbook",
    "best_bid": "live:orderbook",
    "ask_price": "live:orderbook",
    "best_ask": "live:orderbook",
    "mid_price": "live:orderbook",
    "spread_bps": "live:orderbook",
    "day_open": "live:day",
    "day_high": "live:day",
    "day_low": "live:day",
    "day_volume": "live:day",
    "day_turnover": "live:day",
    "open_price": "live:day",
    "high_price": "live:day",
    "low_price": "live:day",
    "volume": "live:day",
    "turnover": "live:day"
  },
  "metadata": {
    "data_status": "partial",
    "partial": true,
    "limitations": [
      "order_book_size_unavailable",
      "price_change_24h_not_mapped_session_semantics",
      "volume_24h_not_mapped_use_day_volume",
      "day_stats_are_session_day_not_rolling_24h",
      "volume_ratio_unavailable_live",
      "listing_id_unavailable_source_code_only",
      "missing_fields"
    ],
    "missing_fields": [
      "price_change_24h",
      "volume_24h",
      "bid_size",
      "ask_size",
      "volume_ratio"
    ],
    "updated_at": "2026-08-05T20:56:00Z",
    "object_refs": []
  }
}
Field notes
  • pricenumber | null
    Latest valid trade price. May be present even when data_status is partial.
  • last_pricenumber | null
    Latest trade price of the current session; same meaning as price.
  • price_change_24hnumber | null
    Absolute price change over the trailing 24 hours. Crypto only — for stocks use session_change_amount / session_change_pct.
  • price_change_24h_absolutenumber | null
    Absolute price change over the trailing 24 hours. Crypto only.
  • price_change_24h_percentnumber | null
    Percent price change over the trailing 24 hours. Crypto only — for stocks use session_change_pct.
  • volume_24hnumber | null
    Cumulative traded quantity over the trailing 24 hours. Crypto only — for stocks use volume / turnover.
  • volume_24h_unitstring | null
    Unit of volume_24h, for example quote-currency notional. Crypto only.
  • amplitudenumber | null
    Intraday amplitude percent = (day high − day low) / previous close × 100. Null when day high/low or previous close is unavailable.
  • open_pricenumber | null
    First valid trade price of the current session.
  • high_pricenumber | null
    Highest trade price of the current session.
  • low_pricenumber | null
    Lowest trade price of the current session.
  • prev_close_pricenumber | null
    Previous trading day close, used as the baseline for change calculations.
  • volumenumber | null
    Cumulative traded quantity in the statistics window, in shares or coins. This is quantity, not value — see turnover for value.
  • turnovernumber | null
    Cumulative traded value in the statistics window, approximately quantity × trade price.
  • avg_pricenumber | null
    Average trade price = turnover ÷ volume. Null when either input is unavailable.
  • volume_rationumber | null
    Current trading volume relative to its historical average. Null with volume_ratio_unavailable_live when no volume-ratio source is available.
  • day_opennumber | null
    Session-day open price, counted per trading day rather than a rolling 24 hours.
  • day_highnumber | null
    Session-day high price, counted per trading day.
  • day_lownumber | null
    Session-day low price, counted per trading day.
  • day_volumenumber | null
    Cumulative traded quantity for the trading day. For stocks prefer this over volume_24h, which is a rolling window.
  • day_turnovernumber | null
    Cumulative traded value for the trading day.
  • session_change_pctnumber | null
    Percent change of the current session versus the previous close. Different from price_change_24h, which is a rolling 24-hour window.
  • session_change_amountnumber | null
    Absolute change amount of the current session versus the previous close.
  • bid_pricenumber | null
    Best bid price at the top of the book. Stock quotes may return a null size with order_book_size_unavailable.
  • ask_pricenumber | null
    Best ask price at the top of the book. Stock quotes may return a null size with order_book_size_unavailable.
  • best_bidnumber | null
    Best bid price; same meaning as bid_price.
  • best_asknumber | null
    Best ask price; same meaning as ask_price.
  • bid_volumenumber | null
    Quantity available at the best bid. Usually null for stock quotes.
  • ask_volumenumber | null
    Quantity available at the best ask. Usually null for stock quotes.
  • mid_pricenumber | null
    Mid of bid/ask when both sides present: (bid + ask) / 2.
  • spread_bpsnumber | null
    Bid-ask spread in basis points relative to mid_price.
  • listing_idstring | null
    Listing id resolved by the server. Omitted when the listing cannot be identified; treat it as unavailable rather than deriving one.
  • venue_idstring | null
    Trading venue id resolved by the server. Treat as unavailable when absent rather than deriving one.
  • tickerstring
    Display ticker or symbol, for example AAPL or BTC.
  • marketstring
    Market code supported by this endpoint (crypto | us_equity | hk_equity).
  • market_sessionstring
    Current trading session phase of the market.
    Enum values
    • pre_marketPre-market session
    • regularRegular trading hours
    • post_marketAfter-hours / post-market
    • closedMarket closed
    • unknownSession unknown
  • snapshot_typestring
    Aggregation scope of this snapshot. Omitted for a single-listing crypto snapshot.
    Enum values
    • multi_venueAggregated across multiple trading venues; venue_quotes has 2 or more rows
    • single_venueScoped to a single listing; venue_quotes has at most one row
  • venue_quotes[]object[]
    Per-venue quote rows. Omitted for a single-listing crypto snapshot; for stocks it appears only when the listing or venue can be identified.
  • venue_quotes[].listing_idstring
    Listing id of this quote row, resolved by the server
  • venue_quotes[].venue_idstring
    Trading venue id of this quote row, resolved by the server
  • venue_quotes[].pricenumber
    Latest trade price on this venue
  • venue_quotes[].volumenumber | null
    Traded quantity on this venue
  • venue_quotes[].volume_24hnumber | null
    Trailing 24-hour traded quantity on this venue, when available
  • venue_quotes[].updated_atiso8601
    Quote time for this venue (UTC ISO-8601)
  • field_sourcesobject
    Maps each field to the kind of source it came from, for example live:session, live:orderbook, or live:day.
  • updated_atiso8601 | null
    Time this quote or response was last updated (UTC ISO-8601).
  • as_of_utciso8601 | null
    Time the quote occurred at the source (UTC ISO-8601). Used to compute source_delay_seconds.
  • source_delay_secondsnumber | null
    How stale the quote is, in seconds (now − as_of_utc/updated_at). Within regular trading hours, a delay above the threshold sets data_status to stale and adds quote_source_latency_high to limitations.
  • snapshot_timeiso8601 | null
    Order-book snapshot time, returned separately when it differs from the last trade time.
  • data_statusstring
    Availability of the business data. Check it before using any numeric field.
    Enum values
    • readyData is complete and usable
    • partialSome fields are missing; price and top-of-book may still be usable
    • staleSource delay above the threshold; see source_delay_seconds
    • no_dataRequest succeeded with no result; unknown ticker returns empty_reason=object_not_found
    • not_readyThis data domain is not open yet
  • metadata.data_statusstring
    Availability of the business data. Same values as the top-level data_status.
    Enum values
    • readyData is complete and usable
    • partialSome fields are missing; price and top-of-book may still be usable
    • staleSource delay above the threshold
    • no_dataRequest succeeded with no result; unknown ticker returns empty_reason=object_not_found
    • not_readyThis data domain is not open yet
  • metadata.partialboolean
    True when the response is expected to be incomplete, matching data_status=partial.
  • metadata.limitationsstring[] | null
    Known data limitations for this response, for example order_book_size_unavailable, volume_ratio_unavailable_live, quote_source_latency_high, or snapshot_stale.
  • metadata.missing_fieldsstring[]
    Names of fields known to be missing, for example price_change_24h, volume_24h, bid_size.
  • metadata.updated_atiso8601 | null
    Time this response was assembled (UTC ISO-8601). May differ slightly from updated_at in the body.
  • empty_reasonstring
    Reason code when there is no data, for example object_not_found or snapshot_expired.
  • reasonstring
    Human-readable explanation for why there is no data.
  • next_actionstring
    Suggested next step when there is no data.
  • try_paramsobject
    Echo of the query parameters used for this request, for example query and market.
  • metadata.object_refs[]object[]
    Unified object references
  • object_refs[].typestring
    Object reference type
  • object_refs[].idstring
    Canonical object identifier
  • object_refs[].entity_idstring
    Canonical entity identifier
  • object_refs[].asset_idstring
    Canonical asset identifier
  • object_refs[].listing_idstring
    Canonical listing identifier
  • object_refs[].instrument_idstring
    Canonical financial instrument identifier
  • object_refs[].venue_idstring
    Canonical trading venue identifier
  • object_refs[].event_refstring
    Related event identifier
  • object_refs[].market_idstring
    Canonical market object identifier
  • object_refs[].venuestring
    Related platform code
  • object_refs[].resolved_fromstring
    Input used to resolve the object
  • object_refs[].resolution_confidencestring
    Object resolution confidence
  • metadata.limitations includes listing_id_unavailable_source_code_onlystring (limitation token)
    The listing could not be identified, so object_refs may be empty while a price is still returned.
How to read results
  • Always read metadata.data_status — equity live is often partial (size/24h) or stale (RTH lag)
  • Prefer day_volume / session_change_*; do not invent volume_24h / price_change_24h from session day
  • Prefer listing_id or query+market; bare ticker without market routes to crypto (no_data)
  • Unknown equity ticker → empty_reason=object_not_found (HTTP 200), not ambiguous_object_resolution
  • Check field_sources (live:session / live:orderbook / live:day) when present

Boundaries & next steps

Do NOT use for
  • Not a tick feed or pro terminal replacement
  • Does not invent crypto rolling 24h from equity session day stats
Common boundaries & status
  • Path is /v1/markets/snapshot — never /v1/markets/stock-state
  • Equity requires market=us_equity|hk_equity; other market endpoints are crypto-only
  • No book size and no rolling 24h volume mapping → partial (accepted); RTH lag → stale
  • Live empty book never silently falls back to an hourly snapshot BBO
BTC live snapshot (crypto) API Reference · snapshot Open My Account