---
title: "Universe Data"
description: "To get the history of a universe, call the history method with the universe object."
canonical: https://www.quantconnect.com/docs/v2/writing-algorithms/historical-data/universe-data
markdown: https://www.quantconnect.com/docs/v2/writing-algorithms/historical-data/universe-data.md
language: python
source: https://github.com/QuantConnect/Documentation/tree/master/03%20Writing%20Algorithms/20%20Historical%20Data/07%20Universe%20Data
modified: 2026-10-30
index: https://www.quantconnect.com/llms.txt
---

# Universe Data

[Documentation](https://www.quantconnect.com/docs/v2.md) > [Writing Algorithms](https://www.quantconnect.com/docs/v2/writing-algorithms.md) > Historical Data > Universe Data

> Code examples are shown in Python. Append `?lang=csharp` to this URL for the C# version of this page.

## Introduction

Universe selection is the process of selecting a basket of assets you may trade. Dynamic universe selection increase diversification and decrease [selection bias](https://en.wikipedia.org/wiki/Selection_bias) in your algorithm. To get the history of a universe, call the `history` method with the universe object. Set the `flatten` argument to `True` to organize the data in a DataFrame for easy pandas wrangling. Note that the `history` method doesn't filter the universe with your filter function. It simply returns all of the assets and data points in the universe dataset.

## US Equity Fundamentals

The following example gets the history of a US Equity [fundamental universe](https://www.quantconnect.com/docs/v2/writing-algorithms/universes/equity/fundamental-universes.md):

```python
class USEquityFundamentalUniverseHistoryAlgorithm(QCAlgorithm):

    def initialize(self) -> None:
        self.set_start_date(2024, 12, 23)
        self.set_end_date(2024, 12, 31)
        # Add a universe of US Equities based on the Fundamentals dataset.
        universe = self.add_universe(lambda fundamentals: [f.symbol for f in fundamentals])
        # Get 5 days of history for the universe.
        history = self.history(universe, timedelta(5), flatten=True)
```

| time | symbol | adjustedprice | assetclassification | companyprofile | companyreference | dollarvolume | earningratios | earningreports | financialstatements | hasfundamentaldata | market | marketcap | operationratios | pricefactor | pricescalefactor | securityreference | splitfactor | valuationratios | value | volume |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 2024-12-19 | A RPTMYV3VC57P | 132.764597 | QuantConnect.Data.Fundamental.AssetClassification | QuantConnect.Data.Fundamental.CompanyProfile | QuantConnect.Data.Fundamental.CompanyReference | 219150734.0 | QuantConnect.Data.Fundamental.EarningRatios | QuantConnect.Data.Fundamental.EarningReports | QuantConnect.Data.Fundamental.FinancialStatements | True | usa | 39348079727 | QuantConnect.Data.Fundamental.OperationRatios | 0.998155 | 0.998155 | QuantConnect.Data.Fundamental.SecurityReference | 1.0 | QuantConnect.Data.Fundamental.ValuationRatios | 133.0100 | 1647626 |
| 2024-12-19 | AA R735QTJ8XC9X | 107.606519 | QuantConnect.Data.Fundamental.AssetClassification | QuantConnect.Data.Fundamental.CompanyProfile | QuantConnect.Data.Fundamental.CompanyReference | 262034107.0 | QuantConnect.Data.Fundamental.EarningRatios | QuantConnect.Data.Fundamental.EarningReports | QuantConnect.Data.Fundamental.FinancialStatements | True | usa | 48093135628 | QuantConnect.Data.Fundamental.OperationRatios | 0.999225 | 0.999225 | QuantConnect.Data.Fundamental.SecurityReference | 1.0 | QuantConnect.Data.Fundamental.ValuationRatios | 107.6900 | 2433226 |
| 2024-12-19 | AA WF7IHVI76I5H | 37.310000 | QuantConnect.Data.Fundamental.AssetClassification | QuantConnect.Data.Fundamental.CompanyProfile | QuantConnect.Data.Fundamental.CompanyReference | 159500884.0 | QuantConnect.Data.Fundamental.EarningRatios | QuantConnect.Data.Fundamental.EarningReports | QuantConnect.Data.Fundamental.FinancialStatements | True | usa | 11995414664 | QuantConnect.Data.Fundamental.OperationRatios | 1.000000 | 1.000000 | QuantConnect.Data.Fundamental.SecurityReference | 1.0 | QuantConnect.Data.Fundamental.ValuationRatios | 37.3100 | 4275017 |
| 2024-12-19 | AAA XHPVXIJUWS4L | 24.822618 | QuantConnect.Data.Fundamental.AssetClassification | QuantConnect.Data.Fundamental.CompanyProfile | QuantConnect.Data.Fundamental.CompanyReference | 494441.0 | QuantConnect.Data.Fundamental.EarningRatios | QuantConnect.Data.Fundamental.EarningReports | QuantConnect.Data.Fundamental.FinancialStatements | False | usa | 0 | QuantConnect.Data.Fundamental.OperationRatios | 0.986947 | 0.986947 | QuantConnect.Data.Fundamental.SecurityReference | 1.0 | QuantConnect.Data.Fundamental.ValuationRatios | 25.1509 | 19659 |
| 2024-12-19 | AAAU WX1HYU092ESL | 25.635000 | QuantConnect.Data.Fundamental.AssetClassification | QuantConnect.Data.Fundamental.CompanyProfile | QuantConnect.Data.Fundamental.CompanyReference | 57235085.0 | QuantConnect.Data.Fundamental.EarningRatios | QuantConnect.Data.Fundamental.EarningReports | QuantConnect.Data.Fundamental.FinancialStatements | False | usa | 0 | QuantConnect.Data.Fundamental.OperationRatios | 1.000000 | 1.000000 | QuantConnect.Data.Fundamental.SecurityReference | 1.0 | QuantConnect.Data.Fundamental.ValuationRatios | 25.6350 | 2232693 |
| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |
| 2024-12-21 | ZUO WTMF35A5I3QD | 9.910000 | QuantConnect.Data.Fundamental.AssetClassification | QuantConnect.Data.Fundamental.CompanyProfile | QuantConnect.Data.Fundamental.CompanyReference | 76550429.0 | QuantConnect.Data.Fundamental.EarningRatios | QuantConnect.Data.Fundamental.EarningReports | QuantConnect.Data.Fundamental.FinancialStatements | True | usa | 1526407764 | QuantConnect.Data.Fundamental.OperationRatios | 1.000000 | 1.000000 | QuantConnect.Data.Fundamental.SecurityReference | 1.0 | QuantConnect.Data.Fundamental.ValuationRatios | 9.9100 | 7724564 |
| 2024-12-21 | ZVIA XQD1725736UD | 3.180000 | QuantConnect.Data.Fundamental.AssetClassification | QuantConnect.Data.Fundamental.CompanyProfile | QuantConnect.Data.Fundamental.CompanyReference | 1620426.0 | QuantConnect.Data.Fundamental.EarningRatios | QuantConnect.Data.Fundamental.EarningReports | QuantConnect.Data.Fundamental.FinancialStatements | True | usa | 91666688 | QuantConnect.Data.Fundamental.OperationRatios | 1.000000 | 1.000000 | QuantConnect.Data.Fundamental.SecurityReference | 1.0 | QuantConnect.Data.Fundamental.ValuationRatios | 3.1800 | 509568 |
| 2024-12-21 | ZVSA Y4A7QNC417J9 | 1.140000 | QuantConnect.Data.Fundamental.AssetClassification | QuantConnect.Data.Fundamental.CompanyProfile | QuantConnect.Data.Fundamental.CompanyReference | 245696.0 | QuantConnect.Data.Fundamental.EarningRatios | QuantConnect.Data.Fundamental.EarningReports | QuantConnect.Data.Fundamental.FinancialStatements | True | usa | 2648935 | QuantConnect.Data.Fundamental.OperationRatios | 1.000000 | 1.000000 | QuantConnect.Data.Fundamental.SecurityReference | 1.0 | QuantConnect.Data.Fundamental.ValuationRatios | 1.1400 | 215523 |
| 2024-12-21 | ZYME WK2S2IM8SSPX | 14.120000 | QuantConnect.Data.Fundamental.AssetClassification | QuantConnect.Data.Fundamental.CompanyProfile | QuantConnect.Data.Fundamental.CompanyReference | 10554318.0 | QuantConnect.Data.Fundamental.EarningRatios | QuantConnect.Data.Fundamental.EarningReports | QuantConnect.Data.Fundamental.FinancialStatements | True | usa | 1075178180 | QuantConnect.Data.Fundamental.OperationRatios | 1.000000 | 1.000000 | QuantConnect.Data.Fundamental.SecurityReference | 1.0 | QuantConnect.Data.Fundamental.ValuationRatios | 14.1200 | 747473 |
| 2024-12-21 | ZYXI X1ZPVR7SWYUD | 8.250000 | QuantConnect.Data.Fundamental.AssetClassification | QuantConnect.Data.Fundamental.CompanyProfile | QuantConnect.Data.Fundamental.CompanyReference | 2580509.0 | QuantConnect.Data.Fundamental.EarningRatios | QuantConnect.Data.Fundamental.EarningReports | QuantConnect.Data.Fundamental.FinancialStatements | True | usa | 296163568 | QuantConnect.Data.Fundamental.OperationRatios | 1.000000 | 1.000000 | QuantConnect.Data.Fundamental.SecurityReference | 1.0 | QuantConnect.Data.Fundamental.ValuationRatios | 8.2500 | 312789 |

```python
# Get the PE Ratio of the first row in the DataFrame.
pe_ratio = history.iloc[0].valuationratios.pe_ratio
```

## US Equity ETF Constituents

The following example gets the history of a US Equity [ETF constituents universe](https://www.quantconnect.com/docs/v2/writing-algorithms/universes/equity/etf-constituents-universes.md):

```python
class ETFConstituentUniverseHistoryAlgorithm(QCAlgorithm):

    def initialize(self) -> None:
        self.set_start_date(2024, 12, 23)
        self.set_end_date(2024, 12, 31)
        # Add a universe of US Equities based on the constituents of an ETF.
        universe = self.add_universe(self.universe.etf('SPY'))
        # Get 5 days of history for the universe.
        history = self.history(universe, timedelta(5), flatten=True)
```

| time | symbol | lastupdate | period | sharesheld | weight |
| --- | --- | --- | --- | --- | --- |
| 2024-12-19 | A RPTMYV3VC57P | 2024-12-17 | 1 days | 3682327.0 | 0.000777 |
| 2024-12-19 | AAPL R735QTJ8XC9X | 2024-12-17 | 1 days | 191633535.0 | 0.075065 |
| 2024-12-19 | ABBV VCY032R250MD | 2024-12-17 | 1 days | 22256743.0 | 0.006032 |
| 2024-12-19 | ABNB XK8H247DY6W5 | 2024-12-17 | 1 days | 5536841.0 | 0.001131 |
| 2024-12-19 | ABT R735QTJ8XC9X | 2024-12-17 | 1 days | 21919703.0 | 0.003837 |
| ... | ... | ... | ... | ... | ... |
| 2024-12-21 | XYL V18KR26TE3XH | 2024-12-19 | 1 days | 2947931.0 | 0.000569 |
| 2024-12-21 | YUM R735QTJ8XC9X | 2024-12-19 | 1 days | 3412693.0 | 0.000737 |
| 2024-12-21 | ZMH S6ZZPKTVDY05 | 2024-12-19 | 1 days | 2471688.0 | 0.000433 |
| 2024-12-21 | ZBRA R735QTJ8XC9X | 2024-12-19 | 1 days | 625772.0 | 0.000400 |
| 2024-12-21 | ZTS VDRJHVQ4FNFP | 2024-12-19 | 1 days | 5484351.0 | 0.001486 |

```python
# Select the 2 assets with the smallest weights in the ETF each day.
daily_smallest = history.groupby('time').apply(lambda x: x.nsmallest(2, 'weight')).reset_index(level=1, drop=True).weight
```

```python
time        symbol
2024-12-19  AMTMW YM37RIGZUD0L    0.000053
            NWSVV VHJF6S7EZRL1    0.000068
2024-12-20  AMTMW YM37RIGZUD0L    0.000051
            NWSVV VHJF6S7EZRL1    0.000069
2024-12-21  AMTMW YM37RIGZUD0L    0.000048
            NWSVV VHJF6S7EZRL1    0.000069
Name: weight, dtype: float64
```

## US Equity Alternative Data

The following example gets the history of a US Equity [alternative data universe](https://www.quantconnect.com/docs/v2/writing-algorithms/universes/equity/alternative-data-universes.md):

```python
class USEquityAltDataUniverseHistoryAlgorithm(QCAlgorithm):

    def initialize(self) -> None:
        self.set_start_date(2024, 12, 23)
        self.set_end_date(2024, 12, 31)
        # Add a universe of US Equities based on an alternative dataset.
        universe = self.add_universe(BrainStockRankingUniverse)
        # Get 5 days of history for the universe.
        history = self.history(universe, timedelta(5), flatten=True)
```

| time | symbol | rank10days | rank21days | rank2days | rank3days | rank5days | value |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 2024-12-18 | A RPTMYV3VC57P | -0.001895 | 0.005938 | -0.007858 | -0.006320 | 0.001771 | -0.007858 |
| 2024-12-18 | AAL VM9RIYHM8ACL | -0.003977 | 0.006520 | -0.005671 | -0.003738 | -0.004715 | -0.005671 |
| 2024-12-18 | AAPL R735QTJ8XC9X | 0.027450 | 0.037339 | 0.006018 | 0.001489 | 0.010102 | 0.006018 |
| 2024-12-18 | ABBV VCY032R250MD | -0.002814 | 0.012297 | -0.001717 | -0.000679 | -0.007454 | -0.001717 |
| 2024-12-18 | ABNB XK8H247DY6W5 | 0.020533 | 0.046173 | -0.002303 | 0.007350 | 0.011252 | -0.002303 |
| ... | ... | ... | ... | ... | ... | ... | ... |
| 2024-12-23 | ZI XF2DKG2HHLK5 | -0.038118 | -0.037527 | -0.035904 | -0.041195 | -0.041388 | -0.035904 |
| 2024-12-23 | ZM X3RPXTZRW09X | 0.006784 | 0.020690 | -0.005674 | -0.008556 | -0.002120 | -0.005674 |
| 2024-12-23 | ZS WSVU0MELFQED | 0.010422 | 0.019619 | -0.003743 | -0.002079 | 0.002778 | -0.003743 |
| 2024-12-23 | ZTO WF2L9EOCSQCL | -0.021455 | -0.015939 | -0.018053 | -0.020263 | -0.024979 | -0.018053 |
| 2024-12-23 | ZTS VDRJHVQ4FNFP | 0.030589 | 0.041400 | 0.024744 | 0.019891 | 0.031048 | 0.024744 |

```python
# Select the asset with the greatest value each day.
daily_winner = history.groupby('time').apply(lambda x: x.nlargest(1, 'value')).reset_index(level=1, drop=True).value
```

```python
time        symbol
2024-12-18  FIC R735QTJ8XC9X    0.054204
2024-12-19  FIC R735QTJ8XC9X    0.073250
2024-12-20  FIC R735QTJ8XC9X    0.065142
2024-12-21  FIC R735QTJ8XC9X    0.065142
2024-12-22  FIC R735QTJ8XC9X    0.065142
2024-12-23  FIC R735QTJ8XC9X    0.065142
Name: value, dtype: float64
```

## Equity Options

The following example gets the history of an [Equity Options universe](https://www.quantconnect.com/docs/v2/writing-algorithms/universes/equity-options.md):

```python
class EquityOptionUniverseHistoryAlgorithm(QCAlgorithm):

    def initialize(self) -> None:
        self.set_start_date(2024, 12, 23)
        self.set_end_date(2024, 12, 31)
        # Add a universe of Equity Option contracts.
        option = self.add_option('SPY')
        # Get 5 days of history for the universe.
        history = self.history(option.symbol, timedelta(5), flatten=True)
```

| time | symbol | close | delta | gamma | high | impliedvolatility | low | open | openinterest | rho | theta | underlying | value | vega | volume |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 2024-12-19 | SPY YOGVNNCO8QDI\|SPY R735QTJ8XC9X | 466.350 | 0.000000 | 0.000000 | 486.910 | 0.000000 | 465.655 | 484.000 | 1543.0 | 0.000000 | 0.000000 | SPY: ¤586.28 | 466.350 | 0.000000 | 7.0 |
| 2024-12-19 | SPY YOGVNNCU72FA\|SPY R735QTJ8XC9X | 455.800 | 0.000000 | 0.000000 | 476.910 | 0.000000 | 455.575 | 474.010 | 31.0 | 0.009492 | -0.000385 | SPY: ¤586.28 | 455.800 | -0.001621 | 5.0 |
| 2024-12-19 | SPY YOGVNND05EH2\|SPY R735QTJ8XC9X | 445.960 | 0.000000 | 0.000000 | 466.910 | 0.000000 | 445.750 | 463.985 | 9.0 | 0.010222 | -0.001891 | SPY: ¤586.28 | 445.960 | -0.005638 | 5.0 |
| 2024-12-19 | SPY YOGVNND63QIU\|SPY R735QTJ8XC9X | 436.445 | 0.000000 | 0.000000 | 456.915 | 0.000000 | 435.545 | 454.005 | 23.0 | 0.010952 | -0.003397 | SPY: ¤586.28 | 436.445 | -0.009656 | 5.0 |
| 2024-12-19 | SPY YTG30NXW11QE\|SPY R735QTJ8XC9X | 438.380 | 1.000000 | 0.000000 | 458.475 | 0.722009 | 437.950 | 456.650 | 33.0 | 0.000000 | 0.000000 | SPY: ¤586.28 | 438.380 | 0.000000 | 0.0 |
| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |
| 2024-12-21 | SPY 33899RRUZK23Q\|SPY R735QTJ8XC9X | 309.500 | -0.867002 | 0.000479 | 357.380 | 0.141164 | 272.505 | 318.220 | 1.0 | -5.758672 | 0.037828 | SPY: ¤591.15 | 309.500 | 0.549488 | 0.0 |
| 2024-12-21 | SPY 337HP99QFUJJA\|SPY R735QTJ8XC9X | 314.500 | -0.877658 | 0.000388 | 362.425 | 0.136831 | 277.490 | 323.190 | 0.0 | -5.659564 | 0.039793 | SPY: ¤591.15 | 314.500 | 0.414755 | 0.0 |
| 2024-12-21 | SPY 33899RVZ5ZO12\|SPY R735QTJ8XC9X | 314.315 | -0.870742 | 0.000427 | 362.370 | 0.138433 | 277.495 | 322.940 | 0.0 | -5.845895 | 0.038531 | SPY: ¤591.15 | 314.315 | 0.481876 | 0.0 |
| 2024-12-21 | SPY 337HP95ZTK8HY\|SPY R735QTJ8XC9X | 319.500 | -0.877873 | 0.000381 | 367.425 | 0.138304 | 282.490 | 328.190 | 0.0 | -5.749542 | 0.040433 | SPY: ¤591.15 | 319.500 | 0.411621 | 0.0 |
| 2024-12-21 | SPY 33899RS8JPCZQ\|SPY R735QTJ8XC9X | 319.500 | -0.869815 | 0.000438 | 367.370 | 0.141717 | 282.495 | 328.200 | 1.0 | -5.941354 | 0.039119 | SPY: ¤591.15 | 319.500 | 0.503219 | 0.0 |

```python
# Find the open interest value at the 99th percentile.
high_open_interest = history.openinterest.quantile(0.99)
```

## Index Options

The following example gets the history of an [Index Options universe](https://www.quantconnect.com/docs/v2/writing-algorithms/universes/index-options.md):

```python
class IndexOptionsUniverseHistoryAlgorithm(QCAlgorithm):

    def initialize(self) -> None:
        self.set_start_date(2024, 12, 23)
        self.set_end_date(2024, 12, 31)
        # Add a universe of Index Option contracts.
        option = self.add_index_option('VIX')
        # Get 5 days of history for the universe.
        history = self.history(option.symbol, timedelta(5), flatten=True)
```

| time | symbol | close | delta | gamma | high | impliedvolatility | low | open | openinterest | rho | theta | underlying | value | vega | volume |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 2024-12-19 | VIX YPDGYCCGNK32\|VIX 31 | 11.500 | 1.000000 | 0.000000 | 11.950 | 0.000000 | 6.425 | 6.575 | 3868.0 | 0.008740 | -0.001349 | VIX: ¤27.65 | 11.500 | 0.000000 | 3747.0 |
| 2024-12-19 | VIX YQ51GYL6SOKU\|VIX 31 | 11.100 | 1.000000 | 0.000000 | 11.825 | 0.000000 | 8.225 | 8.550 | 59.0 | 0.015541 | -0.001343 | VIX: ¤27.65 | 11.100 | 0.000000 | 9.0 |
| 2024-12-19 | VIX YPDGYCB530UM\|VIX 31 | 10.500 | 1.000000 | 0.000000 | 11.050 | 0.000000 | 4.255 | 6.805 | 905.0 | 0.009711 | -0.001499 | VIX: ¤27.65 | 10.500 | 0.000000 | 250.0 |
| 2024-12-19 | VIX YQ51GYJV85CE\|VIX 31 | 10.125 | 1.000000 | 0.000000 | 10.325 | 0.000000 | 7.225 | 7.550 | 225.0 | 0.017268 | -0.001492 | VIX: ¤27.65 | 10.125 | 0.000000 | 112.0 |
| 2024-12-19 | VIX YQVMJHFFAIOE\|VIX 31 | 9.900 | 1.000000 | 0.000000 | 10.225 | 0.000000 | 5.430 | 5.580 | 192.0 | 0.024495 | -0.001486 | VIX: ¤27.65 | 9.900 | 0.000000 | 22.0 |
| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |
| 2024-12-21 | VIX 32P91MEJ8IFXQ\|VIX 31 | 179.925 | -0.987482 | 0.001990 | 182.125 | 2.167690 | 176.675 | 177.700 | 1.0 | -0.330896 | 0.025512 | VIX: ¤18.37 | 179.925 | 0.002433 | 0.0 |
| 2024-12-21 | VIX 32PZMOXESKT9Q\|VIX 31 | 179.150 | -0.984647 | 0.002316 | 180.850 | 1.849262 | 176.050 | 177.350 | 84.0 | -0.475329 | 0.026046 | VIX: ¤18.37 | 179.150 | 0.003485 | 0.0 |
| 2024-12-21 | VIX 32QS6NN0OSOXA\|VIX 31 | 178.425 | -0.981929 | 0.002610 | 180.100 | 1.636117 | 174.450 | 176.875 | 20.0 | -0.629100 | 0.026343 | VIX: ¤18.37 | 178.425 | 0.004620 | 0.0 |
| 2024-12-21 | VIX 32RQNAWTLH3JI\|VIX 31 | 177.500 | -0.981896 | 0.002619 | 179.300 | 1.433080 | 174.200 | 176.225 | 3.0 | -0.812986 | 0.026931 | VIX: ¤18.37 | 177.500 | 0.005274 | 0.0 |
| 2024-12-21 | VIX 32SI7TJ2BM81A\|VIX 31 | 176.725 | -0.982793 | 0.002528 | 178.575 | 1.305996 | 173.400 | 175.600 | 4.0 | -0.958744 | 0.027301 | VIX: ¤18.37 | 176.725 | 0.005495 | 0.0 |

```python
# Get the daily trading volume across all the contracts.
daily_volume = history.groupby('time').apply(lambda x: x.volume.sum())
```

```python
time
2024-12-19    1285753.0
2024-12-20    1374216.0
2024-12-21     833384.0
dtype: float64
```

## Crypto

The following example gets the history of a [Crypto universe](https://www.quantconnect.com/docs/v2/writing-algorithms/universes/crypto.md):

```python
class CryptoUniverseHistoryAlgorithm(QCAlgorithm):

    def initialize(self) -> None:
        self.set_start_date(2024, 12, 23)
        self.set_end_date(2024, 12, 31)
        # Add a universe of Cryptocurrencies.
        universe = self.add_universe(CryptoUniverse.coinbase(lambda data: [x.symbol for x in data]))
        # Get 5 days of history for the universe.
        history = self.history(universe, timedelta(5), flatten=True)
```

| time | symbol | close | high | low | open | price | volume | volumeinusd |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 2024-12-19 | 00USD 2XR | 0.050300 | 0.051500 | 0.049200 | 0.051500 | 0.050300 | 3.173495e+06 | 1.596268e+05 |
| 2024-12-19 | 00USDC 2XR | 0.050300 | 0.051500 | 0.049200 | 0.051500 | 0.050300 | 3.173495e+06 | 1.596268e+05 |
| 2024-12-19 | 1INCHBTC 2XR | 0.000004 | 0.000005 | 0.000004 | 0.000005 | 0.000004 | 9.815380e+03 | 4.584371e+03 |
| 2024-12-19 | 1INCHEUR 2XR | 0.446000 | 0.467000 | 0.442000 | 0.465000 | 0.446000 | 9.007325e+04 | 4.215390e+04 |
| 2024-12-19 | 1INCHGBP 2XR | 0.369000 | 0.385000 | 0.366000 | 0.381000 | 0.369000 | 3.932220e+04 | 1.845807e+04 |
| ... | ... | ... | ... | ... | ... | ... | ... | ... |
| 2024-12-23 | ZETAUSDC 2XR | 0.574500 | 0.638600 | 0.562600 | 0.598400 | 0.574500 | 1.522481e+06 | 8.746654e+05 |
| 2024-12-23 | ZROUSD 2XR | 5.487000 | 6.363000 | 5.393000 | 5.635000 | 5.487000 | 1.312069e+05 | 7.199321e+05 |
| 2024-12-23 | ZROUSDC 2XR | 5.487000 | 6.363000 | 5.393000 | 5.635000 | 5.487000 | 1.312069e+05 | 7.199321e+05 |
| 2024-12-23 | ZRXUSD 2XR | 0.449944 | 0.509425 | 0.441590 | 0.476001 | 0.449944 | 3.371118e+06 | 1.516814e+06 |
| 2024-12-23 | ZRXUSDC 2XR | 0.449944 | 0.509425 | 0.441590 | 0.476001 | 0.449944 | 3.371118e+06 | 1.516814e+06 |

```python
# Get the Crypto with the largest daily return each day.
history['roc'] = (history['close'] - history['open']) / history['open']
top_gainers = history.loc[history.groupby('time')['roc'].idxmax()]
```

| time | symbol | close | high | low | open | price | volume | volumeinusd | roc |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 2024-12-19 | PRQUSD 2XR | 0.19020 | 0.21000 | 0.14930 | 0.15360 | 0.19020 | 1.934896e+07 | 3.680171e+06 | 0.238281 |
| 2024-12-20 | NCTUSD 2XR | 0.03696 | 0.03844 | 0.02740 | 0.02956 | 0.03696 | 2.584655e+08 | 9.552883e+06 | 0.250338 |
| 2024-12-21 | VELOUSD 2XR | 0.22099 | 0.23863 | 0.19002 | 0.20075 | 0.22099 | 8.206130e+07 | 1.813473e+07 | 0.100822 |
| 2024-12-22 | ZENUSD 2XR | 26.10600 | 28.39000 | 15.70500 | 15.83300 | 26.10600 | 5.834163e+05 | 1.523067e+07 | 0.648835 |
| 2024-12-23 | AGLDUSD 2XR | 2.15440 | 2.17030 | 1.30540 | 1.31010 | 2.15440 | 5.144987e+06 | 1.108436e+07 | 0.644455 |

## Crypto Market Cap

The following example gets the history of a [Crypto market cap universe](https://www.quantconnect.com/docs/v2/writing-algorithms/datasets/coingecko/crypto-market-cap.md#08-Universe-Selection):

```python
class CryptoMarketCapUniverseHistoryAlgorithm(QCAlgorithm):

    def initialize(self) -> None:
        self.set_start_date(2024, 12, 24)
        self.set_end_date(2024, 12, 31)
        # Add a universe of Cryptocurrencies.
        universe = self.add_universe(CoinGeckoUniverse)
        # Get 355 days of history for the universe.
        history = self.history(universe, timedelta(365), flatten=True)
```

| time | symbol | coin | marketcap | value | volume |
| --- | --- | --- | --- | --- | --- |
| 2023-12-26 | DAPP.CoinGecko 2S | DAPP | 0.000000e+00 | 0.000111 | 1.203664e+03 |
| 2023-12-26 | FLUID.CoinGecko 2S | FLUID | 3.385875e+07 | 1.886653 | 8.124432e+04 |
| 2023-12-26 | PAAL.CoinGecko 2S | PAAL | 7.678778e+07 | 0.118019 | 3.264158e+06 |
| 2023-12-26 | TOSHI.CoinGecko 2S | TOSHI | 5.358157e+07 | 0.000127 | 9.605914e+05 |
| 2023-12-27 | DAPP.CoinGecko 2S | DAPP | 0.000000e+00 | 0.000109 | 1.189876e+03 |
| ... | ... | ... | ... | ... | ... |
| 2024-12-24 | VIRTUAL.CoinGecko 2S | VIRTUAL | 3.016890e+09 | 3.014802 | 4.121598e+08 |
| 2024-12-24 | XION.CoinGecko 2S | XION | 7.990578e+07 | 3.126583 | 1.454954e+07 |
| 2024-12-24 | ZAP.CoinGecko 2S | ZAP | 3.094296e+06 | 0.032612 | 1.781765e+05 |
| 2024-12-24 | ZEREBRO.CoinGecko 2S | ZEREBRO | 3.018897e+08 | 0.300990 | 7.376285e+07 |
| 2024-12-24 | ZRC.CoinGecko 2S | ZRC | 1.660151e+08 | 0.075640 | 1.373892e+08 |

```python
# Select the largest Crypto each day.
largest_coin = history.groupby('time').apply(
    lambda x: x.nlargest(1, 'marketcap')
).reset_index(level=1, drop=True).marketcap
```

```python
time        symbol
2023-12-26  PAAL.CoinGecko 2S       7.678778e+07
2023-12-27  PAAL.CoinGecko 2S       6.908865e+07
2023-12-28  PAAL.CoinGecko 2S       1.019541e+08
2023-12-29  PAAL.CoinGecko 2S       1.007006e+08
2023-12-30  PAAL.CoinGecko 2S       8.907086e+07
                                        ...
2024-12-20  VIRTUAL.CoinGecko 2S    2.297529e+09
2024-12-21  VIRTUAL.CoinGecko 2S    2.811267e+09
2024-12-22  VIRTUAL.CoinGecko 2S    2.476485e+09
2024-12-23  VIRTUAL.CoinGecko 2S    2.328428e+09
2024-12-24  VIRTUAL.CoinGecko 2S    3.016890e+09
Name: marketcap, Length: 365, dtype: float64
```

## Custom Data

The following example gets the history of a [custom data universe](https://www.quantconnect.com/docs/v2/writing-algorithms/importing-data/streaming-data/custom-universes/key-concepts.md):

```python
# Define the custom data class outside of the algorithm class.
class StockDataSource(PythonData):

    def get_source(self, config: SubscriptionDataConfig, date: datetime, is_live: bool) -> SubscriptionDataSource:
        return SubscriptionDataSource(
            "https://raw.githubusercontent.com/QuantConnect/Documentation/master/Resources/datasets/custom-data/csv-universe-example.csv",
            SubscriptionTransportMedium.REMOTE_FILE,
            FileFormat.CSV
        )

    def reader(self,config: SubscriptionDataConfig, line: str, date: datetime, is_live: bool) -> BaseData:
        stocks = StockDataSource()
        stocks.symbol = config.symbol
        if not (line.strip() and line[0].isdigit()):
            return stocks
        csv = line.split(',')
        try:
            stocks.time = datetime.strptime(csv[0], "%Y%m%d")
            stocks.end_time = stocks.time + timedelta(days=1)
            stocks["Symbols"] = csv[1:]
        except ValueError:
            StockDataSource.algorithm.log(f'{date}: ValueError')
        return stocks

class CustomDataUniverseHistoryAlgorithm(QCAlgorithm):

    def initialize(self) -> None:
        self.set_start_date(2024, 9, 1)
        self.set_end_date(2024, 12, 31)
        # Attach the algorithm instance to the custom data class to enable logging.
        StockDataSource.algorithm = self
        # Add a custom data universe.
        universe = self.add_universe(StockDataSource)
        # Get the universe history.
        history = self.history(universe, datetime(2018, 1, 1), datetime(2018, 1, 10), flatten=True)
```

| symbol | time | symbols |
| --- | --- | --- |
| STOCKDATASOURCE-USA-AE903F8D-F507-4638-BBFC-EE65760179AE.StockDataSource 2S | 2018-01-04 | [SPY, QQQ, AAPL, IWM, FB] |
| STOCKDATASOURCE-USA-AE903F8D-F507-4638-BBFC-EE65760179AE.StockDataSource 2S | 2018-01-05 | [AAPL, QQQ, IWM, FB, GOOGL] |
| STOCKDATASOURCE-USA-AE903F8D-F507-4638-BBFC-EE65760179AE.StockDataSource 2S | 2018-01-06 | [QQQ, IWM, FB, BAC, GOOGL] |
| STOCKDATASOURCE-USA-AE903F8D-F507-4638-BBFC-EE65760179AE.StockDataSource 2S | 2018-01-07 | [IWM, FB, GOOGL, BAC, GOOG] |
| STOCKDATASOURCE-USA-AE903F8D-F507-4638-BBFC-EE65760179AE.StockDataSource 2S | 2018-01-08 | [IWM, FB, GOOGL, BAC, GOOG] |
| STOCKDATASOURCE-USA-AE903F8D-F507-4638-BBFC-EE65760179AE.StockDataSource 2S | 2018-01-09 | [IWM, FB, GOOGL, BAC, GOOG] |
| STOCKDATASOURCE-USA-AE903F8D-F507-4638-BBFC-EE65760179AE.StockDataSource 2S | 2018-01-10 | [IWM, BAC, GOOGL, GOOG, IBM] |

```python
# Count the number of assets in the universe each day.
universe_size = history.apply(lambda row: len(row.symbols), axis=1).reset_index(level=0, drop=True)
```

```python
time
2018-01-04    5
2018-01-05    5
2018-01-06    5
2018-01-07    5
2018-01-08    5
2018-01-09    5
2018-01-10    5
dtype: int64
```

## Examples

The following examples demonstrate some common practices for trading with historical universe data.

### Example 1: Historical Ranking Prediction

The following example forms an equal-weighted portfolio at the start of each month with the 5 assets that have the greatest 21-day ranking in the Brain ML Stock Ranking dataset.

```python
class UniverseHistoricalDataAlgorithm(QCAlgorithm):

    def initialize(self) -> None:
        self.set_start_date(2024, 9, 1)
        self.set_end_date(2024, 12, 31)
        self.set_cash(1000000)
        self.settings.seed_initial_prices = True

        # Add a monthly update to the universe of BrainStockRanking data.
        self.universe_settings.schedule.on(self.date_rules.month_start("SPY"))
        self._universe = self.add_universe(BrainStockRankingUniverse)

        # Trade on every month's start, based on the predicted rank in the next month.
        self.schedule.on(
            self.date_rules.month_start("SPY"),
            self.time_rules.at(9, 31),
            self.trade
        )

        self.set_warm_up(1)

    def trade(self) -> None:
        # Get the last 5 bars of history for the universe.
        history = self.history(self._universe, 5, fill_forward=False, flatten=True).rank21days.unstack(0)
        # Obtain the 5 highest average rank stocks to invest in equally.
        top_ranked = history.mean(axis=1).nlargest(n=5)
        self.set_holdings([PortfolioTarget(symbol, 0.2) for symbol in top_ranked.index], liquidate_existing_holdings=True)
```