API Reference: Snapshots and Movers
Details
Docs navigation
- Getting started: Quickstart, Authentication, Rate limits, Errors and retries
- Guides: Symbol formats, Timestamps and time zones, Pagination, Split and dividend adjustments, WebSocket streaming, Dataset downloads, Excel and Google Sheets, Changelog
- API reference: Stock bars, Stock trades and quotes, Snapshots and movers (you are here), Tickers, exchanges, calendar, Splits and dividends, Fundamentals and SEC filings, Options chain and Greeks, Options EOD, bars, OI, Forex, Crypto, Crypto derivatives, Futures bars and continuous, Settlements and COT, Indices, Economic data, Technical indicators
- SDKs: Python, JavaScript
The snapshot endpoint answers "where is this stock right now" in one call: last trade, bid and ask, the day's range and volume, and the change from yesterday's close. A second endpoint returns ranked lists of gainers, losers and most active names. This reference covers both, for anyone building a watchlist, a dashboard or a scanner on the stock snapshot endpoint.
Early access. Planned v1 endpoints, not live yet. Free returns prior-close snapshots and end-of-day movers. Starter ($29/mo) gets 15-minute delayed data; Pro ($79/mo) real time from a fee-light source; Business ($249/mo) SIP real time for commercial internal use. Batches of up to 250 symbols work on every plan.
Details
Snapshot
GET https://api.marketdata.co/v1/stocks/snapshot
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
symbols |
string | yes | Comma-separated tickers, up to 250 | |
fields |
string | no | all | Comma-separated subset of fields |
format |
string | no | json |
json or csv |
Response fields
| Field | Type | Description |
|---|---|---|
symbol |
string | Ticker |
timestamp |
string | Time of latest update, ISO 8601 UTC |
last_price |
number | Last trade price |
last_size |
number | Last trade size (optional) |
last_trade_timestamp |
string | Time of last trade (optional) |
bid_price, bid_size |
number | Best bid and shares (optional) |
ask_price, ask_size |
number | Best ask and shares (optional) |
mid_price |
number | (bid + ask) / 2 (optional) |
open, high, low |
number | Session open, high, low |
volume |
number | Session volume |
vwap |
number | Session VWAP (optional) |
previous_close |
number | Prior regular-session close |
change |
number | last_price minus previous_close |
change_percent |
number | Change in percent |
pre_market_price |
number | Latest pre-market trade (optional) |
after_hours_price |
number | Latest after-hours trade (optional) |
fifty_two_week_high, fifty_two_week_low |
number | 52-week range (optional) |
market_cap |
number | Shares outstanding times last price (optional) |
is_market_open |
boolean | Regular session open now (optional) |
is_delayed |
boolean | True when data is delayed |
price_source |
string | sip, iex, nasdaq_basic, derived |
Example request
Example (curl):
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.marketdata.co/v1/stocks/snapshot?symbols=TSLA,AAPL,MSFT"
Example (Python), a watchlist sorted by percent change:
import os
import requests
import pandas as pd
watch = ["AAPL", "MSFT", "NVDA", "TSLA", "AMZN", "META"]
r = requests.get(
"https://api.marketdata.co/v1/stocks/snapshot",
headers={"Authorization": f"Bearer {os.environ['MARKETDATA_API_KEY']}"},
params={"symbols": ",".join(watch)},
)
snap = pd.DataFrame(r.json()["results"]).set_index("symbol")
print(snap[["last_price", "change_percent", "volume", "is_delayed"]].sort_values("change_percent"))
Example response
Values are illustrative:
{
"status": "ok",
"count": 1,
"next_cursor": null,
"results": [
{
"symbol": "TSLA",
"timestamp": "2026-11-18T15:42:07.381Z",
"last_price": 341.28,
"bid_price": 341.25,
"ask_price": 341.3,
"mid_price": 341.275,
"open": 335.1,
"high": 343.9,
"low": 333.42,
"volume": 61248930,
"previous_close": 334.65,
"change": 6.63,
"change_percent": 1.98,
"is_market_open": true,
"is_delayed": false,
"price_source": "iex"
}
]
}
Details
Movers
GET https://api.marketdata.co/v1/stocks/movers
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
list_type |
string | yes | gainers, losers or most_active |
|
asset_type |
string | no | common_stock |
common_stock, etf, or all |
min_price |
number | no | 1 | Skip stocks below this price |
limit |
integer | no | 20 | Up to 100 |
Each result is a full snapshot record plus two fields:
| Field | Type | Description |
|---|---|---|
list_type |
string | The list it came from |
rank |
integer | 1 is the biggest mover |
API
Errors for these endpoints
| HTTP | error.code |
When |
|---|---|---|
| 400 | invalid_parameter |
More than 250 symbols, or unknown list_type |
| 403 | plan_required |
Real-time data requested on a delayed plan (the response falls back only if you pass allow_delayed=true) |
| 404 | symbol_not_found |
Returned per symbol inside errors when a batch has some bad tickers; the good ones still come back |
Watch out
Notes and gotchas
- Always check
is_delayedandprice_sourcebefore showing a price as live. On Pro, real-time prices come from a single venue such as IEX, not the full consolidated tape. - Before the open,
changecompares the last trade (often yesterday's close) withprevious_close, so it can read 0. Usepre_market_pricefor early moves. volumeandvwapcover the regular session plus whatever extended-hours trading your plan includes.- A batch of 250 symbols counts as one request. Polling one symbol at a time burns your rate limit fast.
- For a continuous feed, use WebSocket streaming instead of polling every second.
- Halted stocks keep their last price. Check halt status in trading halts data.
Keep reading
Next steps
Details
Was this page useful?
[Yes] [No]
Want another movers list? Tell us on the custom data form.