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 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 1-minute quote intervals: the last NBBO quote of each minute in which a new quote arrived, for every contract that quoted (see Option 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 option quote flat file carries the last quote of each minute, not the open, high, low and close of trades within it. Use the History OHLC endpoints for bars, and note there is no stock equivalent of the option quote flat file.
- Raw trade-only or tick-level quote-only data. Aside from the option 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.
Option Quote Deduplication
The option quote flat file only sends 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 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.
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))