Flat Files V3
A flat file is a single bulk export containing every trade/quote tick, end-of-day summary, or open interest record for an entire asset class on one date, delivered as one CSV (or JSON/ndjson) stream. For example, the option flat files include every contract for every optionable ticker, not just one symbol.
This is different from the regular History endpoints, which require a symbol per request and have no market-wide wildcard for historical trade/quote/EOD/open-interest data. Use flat files when you need a full day of data across every symbol or contract at once, for backtesting, building a local database, or bulk analysis, instead of making one request per symbol.
Behavior
- Flat files are only available to professional users. The 7 most recent calendar days of data are available.
- Data for the previous day should be available around 12:30am - 1am ET.
- We have tentative plans to ease this limitation in the future.
- If you are interested in procuring more than the 7 days available, contact sales.
| Name | REST Docs | Python Docs | Sample URL | Expected Response Time | Expected Size of CSV |
|---|---|---|---|---|---|
| Option Trade Quote | REST | Python | http://127.0.0.1:25503/v3/option/flat_file/trade_quote?date=20250512 | 3 min | 1.2 GB |
| Option Quote | REST | Python | http://127.0.0.1:25503/v3/option/flat_file/quote?date=20250512 | 30 min | 38 GB |
| Option Open Interest | REST | Python | http://127.0.0.1:25503/v3/option/flat_file/open_interest?date=20250512 | 1 min | 50 MB |
| Option EOD | REST | Python | http://127.0.0.1:25503/v3/option/flat_file/eod?date=20250512 | 1 min | 150 MB |
| Stock Trade Quote | REST | Python | http://127.0.0.1:25503/v3/stock/flat_file/trade_quote?date=20250512 | 30 min | 14 GB |
| Stock Quote | REST | Python | http://127.0.0.1:25503/v3/stock/flat_file/quote?date=20250512 | TBD | TBD |
| Stock EOD | REST | Python | http://127.0.0.1:25503/v3/stock/flat_file/eod?date=20250512 | 1 sec | 1.5 MB |
| Index EOD | REST | Python | http://127.0.0.1:25503/v3/index/flat_file/eod?date=20250512 | 1 sec | 1 MB |
What's Included
- Option and stock trade/quote ticks (every trade paired with the last NBBO quote at the time of the trade).
- Option and stock 1-minute quote intervals: the last NBBO quote of each minute in which a new quote arrived, for every contract or symbol that quoted (see Quote Deduplication).
- Option, stock, and index end-of-day summaries (OHLC, volume, count, and the closing NBBO quote).
- Option open interest.
What's Not Included
- Intraday OHLC bars (e.g. 1-minute bars). The quote flat files carry the last quote of each minute, not the open, high, low and close of trades within it. Use the History OHLC endpoints for bars.
- Raw trade-only or tick-level quote-only data. Aside from the 1-minute quote intervals above, flat files offer the combined trade/quote export rather than a trade-only or every-quote stream. Use the History Trade endpoints instead.
- Greeks and implied volatility (delta, gamma, IV, etc.). None of the greeks endpoints have a flat file equivalent.
- At-Time (point-in-time) and Snapshot (real-time) data.
Quote Deduplication
The option and stock quote flat files only send a row for a minute in which a new quote arrived. A minute whose quote is the same as the previous minute's is left out, as are the minutes before a contract's or symbol's first quote of the day.
Each row has two timestamps: interval_ms_of_day is the minute the row belongs to, and quote_ms_of_day is when the quote itself was reported. For example, a contract quoted at 9:30:12 and next at 9:33:40 produces only two rows (times shown as clock times rather than milliseconds):
| interval_ms_of_day | quote_ms_of_day |
|---|---|
| 9:31:00 | 9:30:12 |
| 9:34:00 | 9:33:40 |
The 9:32 and 9:33 minutes are not sent because they still hold the 9:30:12 quote. To rebuild every minute, carry each row forward until the next row for that contract or symbol.
Python
The Python library exposes each flat file endpoint as a client method that returns a dataframe:
from thetadata import ThetaClient
from datetime import date
client = ThetaClient(dataframe_type='polars')
df = client.option_flat_file_trade_quote(date=date(2024, 1, 2))