Stock snapshot endpoints provide market-state views for all stocks, one ticker, or directional movers.
Full market snapshot
GET /v1/stocks/snapshot/
curl "https://api.cutemarkets.com/v1/stocks/snapshot/" \
-H "Authorization: Bearer YOUR_API_KEY"
Common query parameters include include_otc, ticker.any_of, and limit where supported by the endpoint.
Ticker snapshot
GET /v1/stocks/snapshot/{ticker}/
curl "https://api.cutemarkets.com/v1/stocks/snapshot/AAPL/" \
-H "Authorization: Bearer YOUR_API_KEY"
The response is a single snapshot object in the standard CuteMarkets envelope.
Movers
GET /v1/stocks/snapshot/movers/{direction}/
direction is gainers or losers.
curl "https://api.cutemarkets.com/v1/stocks/snapshot/movers/gainers/?limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
Plan behavior
Free and Developer stock subscriptions receive delayed snapshot data. Expert and Commercial stock subscriptions receive live stock data.
Choosing a snapshot endpoint
Use the smallest snapshot surface that answers the product question. A full market snapshot is useful for broad screens, but a ticker snapshot is cleaner for a detail page, and movers are better for leaderboard-style UIs.
| Endpoint | Best for | Avoid when |
|---|---|---|
/v1/stocks/snapshot/ | Market-wide scans and batch refreshes. | The user already selected one ticker. |
/v1/stocks/snapshot/{ticker}/ | Detail pages, watchlists, and stock context beside an option chain. | You need historical bars or trades. |
/v1/stocks/snapshot/movers/{direction}/ | Gainers and losers dashboards. | You need custom ranking logic across your own universe. |
Snapshot fields in application design
A snapshot should be treated as current state, not as a historical record. Store the request time, the ticker, the plan freshness, and the snapshot timestamp fields your application displays. When a stock snapshot is used beside an options chain, label it as underlying context so users do not confuse stock state with option contract state.
Refresh strategy
Snapshot endpoints are often used in interfaces that refresh repeatedly. Pick the refresh interval based on the product question rather than refreshing every card at the same speed. A watchlist can tolerate slower polling than a focused ticker panel. A movers screen may refresh on a schedule and then sort locally. A stock context block beside an options chain should refresh only when the surrounding chain or selected ticker changes, unless the interface is explicitly live.
Always make plan freshness visible in the data model. Free and Developer stock subscriptions receive delayed data, while Expert and Commercial subscriptions receive live stock data. If a screen combines delayed stock snapshots with live options data, label the timeframes so users do not compare values as if they were measured at the same instant.
Snapshot versus historical endpoints
Use snapshots for the latest state and historical endpoints for reproducible analysis. If a user opens a ticker detail page, a snapshot can populate price, change, and current market state quickly. If a chart, model, or alert needs to explain how price moved over a period, use aggregates, trades, quotes, or open-close data with explicit date filters.
This distinction matters for audits. A stored snapshot response can show what the application displayed, but it does not replace a historical data query. If a signal is promoted from a dashboard into a research pipeline, store the snapshot request id and then fetch the historical series required to reproduce the signal from first principles.
Product design checklist
- Use full market snapshots for broad overview screens, not single-ticker detail pages.
- Use ticker snapshots after the user has selected a symbol.
- Use movers endpoints for simple gainers/losers leaderboards.
- Use custom ranking over aggregates or snapshots when the leaderboard has proprietary rules.
- Pair stock snapshots with option chain data only as underlying context.