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 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 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, 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). Flat files only offer tick-level trade/quote data or a single end-of-day summary, not interval bars. Use the History OHLC endpoints instead.
- Raw trade-only or quote-only data. Flat files only offer the combined trade/quote export, not a trade-only or quote-only 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.
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))