API Reference: Stock Trades and Quotes
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 (you are here), Snapshots and movers, 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
Two endpoints return tick-level US stock data: every trade print (time and sales) and every change to the best bid and offer. This page covers the stock trades API endpoint and the quotes endpoint, their parameters and fields, and the condition codes and ordering rules you need to build correct bars or measure spreads from ticks.
Early access. Planned v1 endpoints, not live yet. Trades: Pro ($79/mo) gets 15-minute delayed trades and 10 years of history; Business ($249/mo) real-time SIP and full history. Quotes: Pro gets live top of book from a single fee-light venue and 1 year of NBBO history; Business gets SIP NBBO and full history.
Details
Trades
GET https://api.marketdata.co/v1/stocks/trades
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
symbol |
string | yes | Ticker | |
date |
string | one of date or start |
One trading day, YYYY-MM-DD |
|
start |
string | UTC timestamp, inclusive | ||
end |
string | no | end of start day |
UTC timestamp, exclusive |
exchange |
string | no | all | Venue MIC filter, e.g. XNAS |
include_off_exchange |
boolean | no | true |
Include TRF and dark pool prints |
session |
string | no | all |
regular, extended, all |
limit |
integer | no | 5,000 | Max 50,000 |
cursor, format |
string | no | Paging and json or csv |
Response fields
| Field | Type | Description |
|---|---|---|
symbol |
string | Ticker |
timestamp |
string | SIP timestamp, ISO 8601 UTC, nanoseconds |
participant_timestamp |
string | Exchange's own timestamp (optional) |
price |
number | Trade price |
size |
number | Shares, odd lots included |
exchange |
string | Venue MIC |
conditions |
array | Sale condition codes, e.g. @, F, T, I |
tape |
string | A (NYSE), B (Arca and others), C (Nasdaq) |
trade_id |
string | Venue trade ID (optional) |
sequence_number |
number | SIP sequence number |
is_off_exchange |
boolean | True for TRF and dark pool prints |
trf_id |
string | Reporting facility ID for off-exchange prints (optional) |
correction |
number | Correction indicator (optional) |
bid_price, ask_price |
number | NBBO at trade time (optional) |
aggressor_side |
string | buy, sell, unknown (optional) |
session |
string | pre, regular, post, overnight |
Example request and response
Example (curl):
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.marketdata.co/v1/stocks/trades?symbol=AAPL&date=2026-11-18&limit=50000"
Example response (illustrative values):
{
"status": "ok",
"count": 50000,
"next_cursor": "eyJzIjoxMDQ4MjMxfQ",
"results": [
{
"symbol": "AAPL",
"timestamp": "2026-11-18T14:30:01.204518337Z",
"participant_timestamp": "2026-11-18T14:30:01.204390112Z",
"price": 228.43,
"size": 100,
"exchange": "XNAS",
"conditions": ["@"],
"tape": "C",
"trade_id": "52983525029461",
"sequence_number": 1048231,
"is_off_exchange": false,
"bid_price": 228.42,
"ask_price": 228.44,
"aggressor_side": "buy",
"session": "regular"
}
]
}
Details
Quotes (NBBO)
GET https://api.marketdata.co/v1/stocks/quotes
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
symbol |
string | yes | Ticker | |
date or start / end |
string | yes | As for trades | |
quote_type |
string | no | nbbo |
nbbo or exchange (single-venue BBO) |
limit, cursor, format |
no | As for trades |
Response fields
| Field | Type | Description |
|---|---|---|
symbol |
string | Ticker |
timestamp |
string | SIP timestamp, UTC, nanoseconds |
participant_timestamp |
string | Exchange timestamp (optional) |
bid_price, ask_price |
number | Best bid and ask |
bid_size, ask_size |
number | Shares at each side (shares, not round lots) |
bid_exchange, ask_exchange |
string | Venue of best bid and ask |
quote_type |
string | nbbo or exchange |
conditions |
array | Quote condition codes (optional) |
tape |
string | A, B, C |
sequence_number |
number | SIP sequence number |
Example (Python), average quoted spread in cents for one day:
import os
import requests
import pandas as pd
r = requests.get(
"https://api.marketdata.co/v1/stocks/quotes",
headers={"Authorization": f"Bearer {os.environ['MARKETDATA_API_KEY']}"},
params={"symbol": "SPY", "date": "2026-11-18", "limit": 50000},
)
q = pd.DataFrame(r.json()["results"])
print(((q["ask_price"] - q["bid_price"]) * 100).mean())
API
Errors for these endpoints
| HTTP | error.code |
When |
|---|---|---|
| 400 | missing_parameter |
Neither date nor start given |
| 400 | range_too_large |
start to end spans more than one trading day |
| 403 | plan_required |
Trades below Pro, real-time SIP below Business, or quotes older than 1 year on Pro |
| 404 | symbol_not_found |
Unknown ticker |
Watch out
Notes and gotchas
- Sort by
timestamp, thensequence_number. Several prints can share a nanosecond. - Not every print should go into OHLC. Late reports, odd-lot and average-price conditions are excluded from official highs and lows. Filter on
conditionsif you build your own bars. - Drop rows where
correctionis non-zero if you want the final tape. - Off-exchange prints are reported to a TRF with a delay of up to a few seconds and can look out of sequence. Use
is_off_exchangeto split them out. - A busy stock can print several million trades a day. That is dozens of pages; write each to disk as it arrives.
- For whole years of ticks, a file at $15 per symbol-year (trades) or $25 (NBBO) is cheaper than paging. See dataset downloads.
Keep reading
Next steps
Details
Was this page useful?
[Yes] [No]
Need a field we don't return? Tell us on the custom data form.