Historical Data

History Requests

Introduction

There are two ways to request historical data in your algorithms: direct historical data requests and indirect algorithm warm up. You can use a direct historical data request at any time throughout your algorithm. It returns all of the data you request as a single object.

Key History Concepts

The historical data API has many different options to give you the greatest flexibility in how to apply it to your algorithm.

Time Period Options

You can request historical data based on a trailing number of bars, a trailing period of time, or a defined period of time. If you request data in a defined period of time, the DateTimedatetime objects you provide are based in the algorithm time zone.

Return Formats

Each asset class supports slightly different data formats. When you make a history request, consider what data returns. Depending on how you request the data, history requests return a specific data type. For example, if you don't provide Symbol objects, you get Slice objects that contain the entire universe.

The most popular return type is a DataFrame. If you request a DataFrame, LEAN unpacks the data from Slice objects to populate the DataFrame. If you intend to use the data in the DataFrame to create TradeBar or QuoteBar objects, request that the history request returns the data type you need. Otherwise, LEAN will waste computational resources populating the DataFrame.

Time Index

When your history request returns a DataFrame, the timestamps in the DataFrame are based on the data time zone. When your history request returns a TradeBars, QuoteBars, Ticks, or Slice object, the Time properties of these objects are based on the algorithm time zone, but the EndTime properties of the individual TradeBar, QuoteBar, and Tick objects are based on the data time zonedata time zone. The EndTime is the end of the sampling period and when the data is actually available. For daily US Equity data, this results in data points appearing on Saturday and skipping Monday.

Request Data

The simplest form of history request is for a known set of Symbol objects. This is common for fixed universes of securities or when you need to prepare new securities added to your algorithm. History requests return slightly different data depending on the overload you call. The data that returns is in ascending order from oldest to newest. This order is necessary to use the data to warm up indicators.

Single Symbol History Requests

To request history for a single asset, pass the asset Symbol to the History method. The return type of the method call depends on the history request [Type]<Type>. The following table describes the return type of each request [Type]<Type>:

Request TypeReturn Data Type
No argumentDataFrameList<TradeBar>
TradeBarList[TradeBars]List<TradeBar>
QuoteBarList[QuoteBars]List<QuoteBar>
TickList[Ticks]List<Tick>
alternativeDataClass
(ex: CBOE)
List[alternativeDataClass]
(ex: List[CBOE])
List<alternativeDataClass>
(ex: List<CBOE>)

Each row of the DataFrame represents the prices at a point in time. Each column of the DataFrame is a property of that price data (for example, open, high, low, and close (OHLC)). If you request a DataFrame object and pass TradeBar as the first argument, the DataFrame that returns only contains the OHLC and volume columns. If you request a DataFrame object and pass QuoteBar as the first argument, the DataFrame that returns contains the OHLC of the bid and ask and it contains OHLC columns, which are the respective means of the bid and ask OHLC values. If you request a DataFrame and don't pass TradeBar or QuoteBar as the first arugment, the DataFrame that returns contains columns for all of the data that's available for the given resolution.

# EXAMPLE 1: Requesting By Bar Count: 5 bars at the security resolution:
vix_symbol = self.AddData(CBOE, "VIX", Resolution.Daily).Symbol
cboe_data = self.History[CBOE](vix_symbol, 5)

btc_symbol = self.AddCrypto("BTCUSD", Resolution.Minute).Symbol
trade_bars = self.History[TradeBar](btc_symbol, 5)
quote_bars = self.History[QuoteBar](btc_symbol, 5)
df = self.History(btc_symbol, 5)

// EXAMPLE 1: Requesting By Bar Count: 5 bars at the security resolution:
var vixSymbol = AddData<CBOE>("VIX", Resolution.Daily).Symbol;
var cboeData = History<CBOE>(vixSymbol, 5);

var btcSymbol = AddCrypto("BTCUSD", Resolution.Minute).Symbol;
var tradeBars = History<TradeBar>(btcSymbol, 5);
var quoteBars = History<QuoteBar>(btcSymbol, 5);
var tradeBars2 = History(btcSymbol, 5);
# EXAMPLE 2: Requesting By Bar Count: 5 bars with a specific resolution:
trade_bars = self.History[TradeBar](btc_symbol, 5, Resolution.Daily)
quote_bars = self.History[QuoteBar](btc_symbol, 5, Resolution.Minute)
df = self.History(btc_symbol, 5, Resolution.Minute)

// EXAMPLE 2: Requesting By Bar Count: 5 bars with a specific resolution:
var tradeBars = History<TradeBar>(btcSymbol, 5, Resolution.Daily);
var quoteBars = History<QuoteBar>(btcSymbol, 5, Resolution.Minute);
var tradeBars2 = History(btcSymbol, 5, Resolution.Minute);
# EXAMPLE 3: Requesting By a Trailing Period: 3 days of data at the security resolution: 
eth_symbol = self.AddCrypto('ETHUSD', Resolution.Tick).Symbol
ticks = self.History[Tick](eth_symbol, timedelta(days=3))

vix_data = self.History[CBOE](vix_symbol, timedelta(days=3)) 
trade_bars = self.History[TradeBar](btc_symbol, timedelta(days=3)) 
quote_bars = self.History[QuoteBar](btc_symbol, timedelta(days=3))
df = self.History(btc_symbol, timedelta(days=3)) 
// EXAMPLE 3: Requesting By a Trailing Period: 3 days of data at the security resolution:
var ethSymbol = AddCrypto("ETHUSD", Resolution.Tick).Symbol;
var ticks = History<Tick>(ethSymbol, TimeSpan.FromDays(3));

var cboeData = History<CBOE>(vixSymbol, TimeSpan.FromDays(3));
var tradeBars = History<TradeBar>(btcSymbol, TimeSpan.FromDays(3));
var quoteBars = History<QuoteBar>(btcSymbol, TimeSpan.FromDays(3));
var tradeBars2 = History(btcSymbol, TimeSpan.FromDays(3));
# EXAMPLE 4: Requesting By a Trailing Period: 3 days of data with a specific resolution: 
trade_bars = self.History[TradeBar](btc_symbol, timedelta(days=3), Resolution.Daily) 
quote_bars = self.History[QuoteBar](btc_symbol, timedelta(days=3), Resolution.Minute)
ticks = self.History[Tick](eth_symbol, timedelta(days=3), Resolution.Tick)
df = self.History(btc_symbol, timedelta(days=3), Resolution.Hour) 

# Important Note: Period history requests are relative to "now" algorithm time.
// EXAMPLE 4: Requesting By a Trailing Period: 3 days of data with a specific resolution:
var tradeBars = History<TradeBar>(btcSymbol, TimeSpan.FromDays(3), Resolution.Daily);
var quoteBars = History<QuoteBar>(btcSymbol, TimeSpan.FromDays(3), Resolution.Minute);
var ticks = History<Tick>(ethSymbol, TimeSpan.FromDays(3), Resolution.Tick);
var tradeBars2 = History(btcSymbol, TimeSpan.FromDays(3), Resolution.Minute);
# EXAMPLE 5: Requesting By a Defined Period: 3 days of data at the security resolution: 
start_time = datetime(2022, 1, 1)
end_time = datetime(2022, 1, 4)

vix_data = self.History[CBOE](vix_symbol, start_time, end_time) 
trade_bars = self.History[TradeBar](btc_symbol, start_time, end_time) 
quote_bars = self.History[QuoteBar](btc_symbol, start_time, end_time)
ticks = self.History[Tick](eth_symbol, start_time, end_time)
df = self.History(btc_symbol, start_time, end_time) 
// EXAMPLE 5: Requesting By a Defined Period: 3 specific days of data at the security resolution:
var startTime = new DateTime(2022, 1, 1);
var endTime = new DateTime(2022, 1, 4);

var cboeData = History<CBOE>(vixSymbol, startTime, endTime);
var tradeBars = History<TradeBar>(btcSymbol, startTime, endTime);
var quoteBars = History<QuoteBar>(btcSymbol, startTime, endTime);
var ticks = History<Tick>(ethSymbol, startTime, endTime);
var tradeBars2 = History(btcSymbol, startTime, endTime);
# EXAMPLE 6: Requesting By a Defined Period: 3 days of data with a specific resolution: 
trade_bars = self.History[TradeBar](btc_symbol, start_time, end_time, Resolution.Daily) 
quote_bars = self.History[QuoteBar](btc_symbol, start_time, end_time, Resolution.Minute)
ticks = self.History[Tick](eth_symbol, start_time, end_time, Resolution.Tick)
df = self.History(btc_symbol, start_time, end_time, Resolution.Hour) 
// EXAMPLE 6: Requesting By a Defined Period: 3 days of data with a specific resolution:
var tradeBars = History<TradeBar>(btcSymbol, startTime, endTime, Resolution.Daily);
var quoteBars = History<QuoteBar>(btcSymbol, startTime, endTime, Resolution.Minute);
var ticks = History<Tick>(ethSymbol, startTime, endTime, Resolution.Tick);
var tradeBars2 = History(btcSymbol, startTime, endTime, Resolution.Minute);

If you request tick data and there are multiple ticks with the same timestamp, the History method only returns the last tick of the collection.

Multiple Symbol History Requests

To request history for multiple symbols at a time, pass an array of Symbol objects to the same API methods shown in the preceding section. The return type of the method call depends on the history request [Type]<Type>. The following table describes the return type of each request [Type]<Type>:

Request TypeReturn Data Type
No argumentDataFrameList<Slice>
TradeBarList[TradeBars]List<TradeBars>
QuoteBarList[QuoteBars]List<QuoteBars>
TickList[Ticks]List<Ticks>
alternativeDataClass
(ex: CBOE)
List[Dict[Symbol, alternativeDataClass]]
(ex: List[Dict[Symbol, CBOE]])
List<Dictionary<Symbol, alternativeDataClass>>
(ex: List<Dictionary<Symbol, CBOE>>)

The Slice return type provides a container that supports all data types. For example, a history request for Forex QuoteBars and Equity TradeBars has the Forex data under slices.QuoteBars and the Equity data under slices.Bars.

# EXAMPLE 7: Requesting By Bar Count for Multiple Symbols: 2 bars at the security resolution:
vix = self.AddData[CBOE]("VIX", Resolution.Daily).Symbol
v3m = self.AddData[CBOE]("VIX3M", Resolution.Daily).Symbol
cboe_data = self.History[CBOE]([vix, v3m], 2)

ibm = self.AddEquity("IBM", Resolution.Minute).Symbol
aapl = self.AddEquity("AAPL", Resolution.Minute).Symbol
trade_bars_list = self.History[TradeBar]([ibm, aapl], 2)
quote_bars_list = self.History[QuoteBar]([ibm, aapl], 2)
df = self.History([ibm, aapl], 2)

// EXAMPLE 7: Requesting By Bar Count for Multiple Symbols: 2 bars at the security resolution:
var vixSymbol = AddData<CBOE>("VIX", Resolution.Daily).Symbol;
var v3mSymbol = AddData<CBOE>("VIX3m", Resolution.Daily).Symbol;
var cboeData = History<CBOE>(new[] { vix, v3m }, 2);

var ibm = AddEquity("IBM", Resolution.Minute).Symbol;
var aapl = AddEquity("AAPL", Resolution.Minute).Symbol;
var tradeBarsList = History<TradeBar>(new[] { ibm, aapl }, 2);
var quoteBarsList = History<QuoteBar>(new[] { ibm, aapl }, 2);
# EXAMPLE 8: Requesting By Bar Count for Multiple Symbols: 5 bars with a specific resolution:
trade_bars_list = self.History[TradeBar]([ibm, aapl], 5, Resolution.Daily)
quote_bars_list = self.History[QuoteBar]([ibm, aapl], 5, Resolution.Minute)
df = self.History([ibm, aapl], 5, Resolution.Daily)

// EXAMPLE 8: Requesting By Bar Count for Multiple Symbols: 5 bars with a specific resolution:
var tradeBarsList = History<TradeBar>(new[] { ibm, aapl }, 5, Resolution.Minute);
var quoteBarsList = History<QuoteBar>(new[] { ibm, aapl }, 5, Resolution.Minute);
# EXAMPLE 9: Requesting By Trailing Period: 3 days of data at the security resolution: 
ticks = self.History[Tick]([eth_symbol], timedelta(days=3))

trade_bars = self.History[TradeBar]([btc_symbol], timedelta(days=3)) 
quote_bars = self.History[QuoteBar]([btc_symbol], timedelta(days=3))
df = self.History([btc_symbol], timedelta(days=3)) 
// EXAMPLE 9: Requesting By Trailing Period: 3 days of data at the security resolution:
var ticks = History<Tick>(new[] {ethSymbol}, TimeSpan.FromDays(3));

var tradeBars = History<TradeBar>(new[] {btcSymbol}, TimeSpan.FromDays(3));
var quoteBars = History<QuoteBar>(new[] {btcSymbol}, TimeSpan.FromDays(3));
var tradeBars2 = History(new[] {btcSymbol}, TimeSpan.FromDays(3));
# EXAMPLE 10: Requesting By Defined Period: 3 days of data at the security resolution: 
trade_bars = self.History[TradeBar]([btc_symbol], start_time, end_time) 
quote_bars = self.History[QuoteBar]([btc_symbol], start_time, end_time)
ticks = self.History[Tick]([eth_symbol], start_time, end_time)
df = self.History([btc_symbol], start_time, end_time) 
// EXAMPLE 10: Requesting By Defined Period: 3 days of data at the security resolution:
var tradeBars = History<TradeBar>(new[] {btcSymbol}, startTime, endTime);
var quoteBars = History<QuoteBar>(new[] {btcSymbol}, startTime, endTime);
var ticks = History<Tick>(new[] {ethSymbol}, startTime, endTime);
var tradeBars2 = History(new[] {btcSymbol}, startTime, endTime);

If you request tick data and there are multiple ticks with the same timestamp for a single security, the History method only returns the last tick of the collection.

All Symbol History Requests

You can request history for all active securities in your universe. The parameters are very similar to other history method calls, but the return type is an array of Slice objects. The Slice object holds all of the results in a sorted enumerable collection that you can iterate over with a loop.

# EXAMPLE 11: Requesting 5 bars for all securities at their respective resolution:

# Create subscriptions
self.AddEquity("IBM", Resolution.Daily)
self.AddEquity("AAPL", Resolution.Daily)

# Request history data and enumerate results
slices = self.History(5)
for s in slices:
    self.Log(str(s.Time) + " AAPL:" + str(s.Bars["AAPL"].Close) + " IBM:" + str(s.Bars["IBM"].Close))

// EXAMPLE 11: Requesting 5 bars for all securities at their respective resolution:

// Set up the universe
AddEquity("IBM", Resolution.Daily);
AddEquity("AAPL", Resolution.Daily);

// Request history data and enumerate results:
var slices = History(5);
foreach (var s in slices) {
    var aaplClose = s.Bars["AAPL"].Close;
    var ibmClose = s.Bars["IBM"].Close;
    Log($"{s.Time} AAPL: {aaplClose} IBM: {ibmClose}");
}

# EXAMPLE 12: Requesting 5 minutes for all securities:

slices = self.History(timedelta(minutes=5), Resolution.Minute)
for s in slices:
    self.Log(str(s.Time) + " AAPL:" + str(s.Bars["AAPL"].Close) + " IBM:" + str(s.Bars["IBM"].Close))

# timedelta history requests are relative to "now" in algorithm Time. If you request this data at 16:05, it returns an empty array because the market is closed.
// EXAMPLE 12: Requesting 24 hours of hourly data for all securities:

var slices = History(TimeSpan.FromHours(24), Resolution.Hour);
foreach (var s in slices) {
    var aaplClose = s.Bars["AAPL"].Close;
    var ibmClose = s.Bars["IBM"].Close;
    Log($"{s.Time} AAPL: {aaplClose} IBM: {ibmClose}");
}

// TimeSpan history requests are relative to "now" in algorithm Time.

Assumed Default Values

The following table describes the assumptions of the History API:

ArgumentAssumption
ResolutionLEAN guesses the resolution you request by looking at the securities you already have in your algorithm. If you have a security subscription in your algorithm with a matching Symbol, the history request uses the same resolution as the subscription. If you don't have a security subscription in your algorithm with a matching Symbol, Resolution.Minute is the default.
Bar typeIf you don't specify a type for the history request, TradeBar is the default. If the asset you request data for doesn't have TradeBar data, specify the QuoteBar type to receive history.

Additional Options

If you call the History method with a list of Symbol objects, a start date, an end date, and a resolution, then you can pass the following additional arguments:

ArgumentData TypeDescriptionDefault Value
fillForwardbool?bool/NoneTypeTrue to fill forward missing data. Otherwise, false.nullNone
extendedMarketbool?bool/NoneTypeTrue to include extended market hours data. Otherwise, false.nullNone
dataMappingModeDataMappingMode?DataMappingMode/NoneTypeThe contract mapping mode to use for the security history request.nullNone
dataNormalizationModeDataNormalizationMode?DataNormalizationMode/NoneTypeThe price scaling mode to use for US Equities or continuous Futures contracts. If you don't provide a value, it uses the data normalization mode of the security subscription.nullNone
contractDepthOffsetint?int/NoneTypeThe desired offset from the current front month for continuous Futures contracts.nullNone
self.future = self.AddFuture(Futures.Currencies.BTC)
history = self.History(
    tickers=[self.future.Symbol], 
    start=self.Time - timedelta(days=15), 
    end=self.Time, 
    resolution=Resolution.Minute, 
    fillForward=False, 
    extendedMarket=False, 
    dataMappingMode=DataMappingMode.OpenInterest, 
    dataNormalizationMode=DataNormalizationMode.Raw, 
    contractDepthOffset=0)
var future = AddFuture(Futures.Currencies.BTC);
var history = History(
    symbols: new[] {future.Symbol}, 
    start: Time - TimeSpan.FromDays(15),
    end: Time,
    resolution: Resolution.Minute,
    fillForward: false,
    extendedMarket: false,
    dataMappingMode: DataMappingMode.OpenInterest,
    dataNormalizationMode: DataNormalizationMode.Raw,
    contractDepthOffset: 0);

Analyze Results

The History method returns a multi-index DataFrame where the first index is the Symbol. The data is then sorted in rows according to the second index, the EndTime of the bar. By learning a few helpful shortcuts, you can directly access the history values you need for your algorithm.

# Setup the universe:
eurusd = self.AddForex("EURUSD", Resolution.Daily).Symbol
nzdusd = self.AddForex("NZDUSD", Resolution.Daily).Symbol

# STEP 1:  Request a DataFrame:
self.df = self.History([eurusd, nzdusd], 3)



# STEP 2: Check if the DataFrame is empty and lock onto a Symbol index with the `loc[]` method.
#  You can access a security’s data in a DataFrame by using the Symbol or the string representation of the Symbol
if not self.df.empty:
    eurusd_quotebars = self.df.loc[eurusd] # or just "EURUSD" instead of Symbol



# STEP 3: Extract and manipulate a single column with the string column name
spread = eurusd_quotebars["askclose"] - eurusd_quotebars["bidclose"]

# Make sure to use the lowercase string column name.

To perform analysis between assets, you can unstack the DataFrame. The unstack method transforms each column into the Symbol values for one of the price-columns you select.

# UNSTACKING: Transform into columns

# Fetch multi-indexed history:
self.dataframe = self.History([self.Symbol("IBM"), self.Symbol("AAPL")], 3)


# Transform using unstack:
self.dataframe["close"].unstack(level=0)

# Make sure to use the lowercase string column name.

The History method returns an array of TradeBar, QuoteBar, or Slice objects, depending on how you call the method. To access the members of each of these objects, iterate over the objects in a for loop.

// Set up the universe
var spy = AddEquity("SPY").Symbol;
var aapl = AddEquity("AAPL").Symbol;

// Example 1: Iterate over TradeBar objects
var tradeBars = History(spy, 10);
foreach (var tradeBar in tradeBars)
{
    Debug($"{tradeBar.Time}: {tradeBar.Close}");
}

// Example 2: Iterate over QuoteBar objects
var quoteBars = History(aapl, 10);
foreach (var quoteBar in quoteBars)
{
     Debug($"{s.Time}: {quoteBar.Bid.Close} / {quoteBar.Ask.Close}");
}

// Example 3: Iterate over Slice objects
var slices = History(new[] {spy, aapl}, 10);
foreach (var slice in slices)
{
    Debug($"{slice.Time}: AAPL {slice.QuoteBars[aapl].Bid.Close}, SPY {slice[spy].Close}");
}

Data Formats

We provide a specific data formats for each asset class. To view the available data formats, see the Resolutions documentation of the following asset classes:

Common Errors

Errors can occur when you request historical data.

Empty Data Errors

If the history request returns an empty DataFrame and you try to slice it, it throws an exception. To avoid issues, check if the DataFrame contains data before slicing it.

df = self.History(symbol, 10).close    # raises exception if the request is empty

def GetSafeHistoryCloses(self, symbols):
    if not symbols:
        self.Log(f'No symbols')
        return  False, None
    df = self.History(symbols, 100, Resolution.Daily)
    if df.empty:
        self.Log(f'Empy history for {symbols}')
        return  False, None
     return True, df.close.unstack(0)

If you run algorithms on your local machine and history requests return no data, check if your data directory contains the data you request. To download datasets, see Download.

Numerical Precision Errors

Some factor files have INF split values, which indicate that the stock has so many splits that prices can't be calculated with correct numerical precision. To allow history requests with these symbols, we need to move the starting date forward when reading the data. If there are numerical precision errors in the factor files for a security in your history request, LEAN throws the following error:

"Warning: when performing history requests, the start date will be adjusted if there are numerical precision errors in the factor files."

Live Trading Considerations

In live trading, if you make a history request for minute data at noon and the history period covers the start of the previous day to the present moment, the data from the previous day will be backtest data. The data of the current day will be live data that we collected throughout the morning. If you make this history request in a backtest, you might get slightly different data for the current day because of post-processing from the data vendor.

You can also see our Videos. You can also get in touch with us via Discord.

Did you find this page helpful?

Contribute to the documentation: