Drawdown Series
Calculate the drawdown in every period: how far an asset stands below its highest value so far, or the gain it needs to get back there.
The drawdown series, also known as the underwater curve, shows the whole history of losses from a previous high instead of only the worst one. It is 0 at every new high and negative while the value is below one, so its lowest point is the Maximum Drawdown (see get_maximum_drawdown) and the stretches below 0 are the drawdowns that get_drawdown_table lists.
Losses and gains are not symmetric: after a fall of 20% the asset needs a gain of 25% to be back at its high, after a fall of 50% a gain of 100%. With recovery=True the series shows that gain, the return needed from each period’s value to get back to the running peak.
The formula is as follows:
\[\operatorname{Wealth}(t) = \text{Π} (1 + \operatorname{Return}(s)) \text{for}\; s \leq t\] \[\operatorname{Peak}(t) = \max(1,\; \max(\operatorname{Wealth}(s) \text{for}\; s \leq t))\] \[\operatorname{Drawdown}(t) = \operatorname{Wealth}(t) / \operatorname{Peak}(t) - 1\] \[\text{Recovery Needed} (t) = \operatorname{Peak}(t) / \operatorname{Wealth}(t) - 1 = - \operatorname{Drawdown}(t) / (1 + \operatorname{Drawdown}(t))\]Returns are total returns (Adj Close). Wealth starts at 1 at the first close of the window, so a decline from the start of the window counts as well.
Also known as: underwater curve, underwater plot, drawdown curve, distance from the high, gain needed to recover, breakeven return, recovery return.
Drawdown Series in Python or via the MCP
Install the Finance Toolkit with:
pip install financetoolkit -U
Then call get_drawdown_series as shown below.
from financetoolkit import Toolkit
toolkit = Toolkit(
["META", "NFLX", "AMZN"],
api_key="FINANCIAL_MODELING_PREP_KEY",
start_date="2021-01-01",
end_date="2025-12-31",
)
toolkit.risk.get_drawdown_series(period="quarterly")
Or, after setting up the Finance Toolkit MCP, ask:
How far below their previous peaks were Meta, Netflix and Amazon at the end of each quarter from 2021 to 2025?
Which returns:
| Date | META | NFLX | AMZN | Benchmark |
|---|---|---|---|---|
| 2021Q1 | 0 | 0 | 0 | 0 |
| 2021Q2 | 0 | 0 | 0 | 0 |
| 2021Q3 | -0.0239 | 0 | -0.0451 | 0 |
| 2021Q4 | -0.0327 | -0.0129 | -0.0308 | 0 |
| 2022Q1 | -0.3605 | -0.3862 | -0.0524 | -0.0461 |
| 2022Q2 | -0.5362 | -0.7134 | -0.3825 | -0.1998 |
| 2022Q3 | -0.6098 | -0.6143 | -0.3431 | -0.2392 |
| 2022Q4 | -0.6539 | -0.5168 | -0.5116 | -0.1817 |
| 2023Q1 | -0.3904 | -0.4339 | -0.3995 | -0.1207 |
| 2023Q2 | -0.1746 | -0.2782 | -0.2421 | -0.0443 |
| 2023Q3 | -0.1365 | -0.3813 | -0.261 | -0.0751 |
| 2023Q4 | 0 | -0.2021 | -0.1168 | 0 |
| 2024Q1 | 0 | -0.0048 | 0 | 0 |
| 2024Q2 | 0 | 0 | 0 | 0 |
| 2024Q3 | 0 | 0 | -0.0358 | 0 |
| 2024Q4 | 0 | 0 | 0 | 0 |
| 2025Q1 | -0.0148 | 0 | -0.1328 | -0.0427 |
| 2025Q2 | 0 | 0 | 0 | 0 |
| 2025Q3 | -0.0043 | -0.1047 | 0 | 0 |
| 2025Q4 | -0.1043 | -0.2998 | 0 | 0 |
Parameters
get_drawdown_series accepts the following parameters.
| Parameter | Type | Description | Example |
|---|---|---|---|
period | str | The data frequency for returns (daily, weekly, monthly, quarterly, or yearly). Defaults to “daily”. | "weekly" |
recovery | bool | Whether to return the gain needed to get back to the running peak (Recovery Needed) instead of the drawdown. Defaults to False. | False |
rounding | int | None | The number of decimals to round the results to. Defaults to None, which uses the rounding of the Toolkit (4 unless set otherwise). | 2 |