Drawdown Table
List the largest drawdowns of each asset with their peak, trough and recovery dates, depth and length.
Where the Maximum Drawdown gives only the single worst decline, the drawdown table shows the largest declines side by side: when each started (the last high before it), when it bottomed out, when the asset was back at its high and how many periods each phase took. It shows whether an asset has one bad episode or recurring ones, and how long recoveries usually take, which a single figure hides. Recovery Needed is the gain needed from the trough to be back at the peak, which is larger than the drawdown itself: a 50% fall needs a 100% gain.
The formula is as follows:
\[\operatorname{Drawdown}(t) = \operatorname{Wealth}(t) / \max(1,\; \max(\operatorname{Wealth}(s) \text{for}\; s \leq t)) - 1 (\text{see}\; \text{get\_drawdown\_series})\]- A drawdown runs from the Peak (the last period at a high) to the Recovery (the first period back at that high), with its Trough at the lowest Drawdown in between
The dates follow pyfolio’s drawdown table (peak, valley and recovery dates). QuantStats and ffn instead start a drawdown at the first period below the peak and count calendar days. The deepest drawdown matches get_maximum_drawdown, get_maximum_drawdown_duration (To Trough) and get_maximum_drawdown_recovery_time (To Recovery).
Also known as: worst drawdowns, drawdown details, drawdown periods, gain needed to recover.
Drawdown Table in Python or via the MCP
Install the Finance Toolkit with:
pip install financetoolkit -U
Then call get_drawdown_table as shown below.
from financetoolkit import Toolkit
toolkit = Toolkit(
["META", "NFLX"],
api_key="FINANCIAL_MODELING_PREP_KEY",
start_date="2021-01-01",
end_date="2025-12-31",
)
toolkit.risk.get_drawdown_table(top=3)
Or, after setting up the Finance Toolkit MCP, ask:
What were the three deepest drawdowns of Meta and Netflix from 2021 to 2025, and how long did each take to recover?
Which returns:
| Peak | Trough | Recovery | Drawdown | Recovery Needed | To Trough | To Recovery | Length | |
|---|---|---|---|---|---|---|---|---|
| (‘META’, 1) | 2021-09-07 | 2022-11-03 | 2024-01-19 | -0.7672 | 3.2955 | 293 | 302 | 595 |
| (‘META’, 2) | 2025-02-14 | 2025-04-21 | 2025-06-30 | -0.3416 | 0.5189 | 44 | 48 | 92 |
| (‘META’, 3) | 2025-08-12 | 2025-11-20 | NaT | -0.2537 | 0.34 | 71 | nan | nan |
| (‘NFLX’, 1) | 2021-11-17 | 2022-05-11 | 2024-08-20 | -0.7593 | 3.1548 | 120 | 571 | 691 |
| (‘NFLX’, 2) | 2025-06-30 | 2025-12-10 | NaT | -0.3076 | 0.4443 | 114 | nan | nan |
| (‘NFLX’, 3) | 2025-02-14 | 2025-04-04 | 2025-04-24 | -0.1916 | 0.237 | 34 | 13 | 47 |
| (‘Benchmark’, 1) | 2022-01-03 | 2022-10-12 | 2023-12-13 | -0.245 | 0.3245 | 195 | 294 | 489 |
| (‘Benchmark’, 2) | 2025-02-19 | 2025-04-08 | 2025-06-26 | -0.1877 | 0.2311 | 34 | 54 | 88 |
| (‘Benchmark’, 3) | 2024-07-16 | 2024-08-05 | 2024-09-19 | -0.0841 | 0.0918 | 14 | 32 | 46 |
Parameters
get_drawdown_table accepts the following parameters.
| Parameter | Type | Description | Example |
|---|---|---|---|
top | int | The number of drawdowns per asset, deepest first. Defaults to 5. | 5 |
period | str | The data frequency for returns (daily, weekly, monthly, quarterly, or yearly). Defaults to “daily”. | "weekly" |
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 |