Tax-aware projection with the recommended withdrawal order
run_tax_aware_projectionRead-only
Runs the retirement projection with the household's accounts split by tax type and returns the withdrawal order and Roth-conversion programme the engine selected, its present-value advantage and range against drawing traditional first, and the after-tax success rate. Federal and state income tax (50 states and DC), Social Security taxability, required minimum distributions, Medicare IRMAA surcharges and the early-withdrawal penalty are paid from the portfolio year by year; spending is what the household keeps after tax. The result states every assumption it used, including the defaults for inputs that were not given, and what the engine does not model.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Two-letter state of residence (or DC) for state income tax with that state's retirement-income rules. When absent the result states that no state tax was modelled. | |
| annuity | No | Optional: a single-life immediate annuity bought at purchase_age with premium (today's dollars) from the traditional IRA (a qualified annuity: payments fully taxable) or the taxable account (non-qualified: each payment is tax-free up to the premium over the IRS Table V multiple until the premium is recovered). Payments start in the purchase year and stop at death. | |
| pension | No | Yearly pension income. Default 0. | |
| lifespan | No | fixed (default): the plan runs to its end age. stochastic: each path draws your death year from the SSA period life table and ends after it (the estate is held at its value at death; success = the money lasted while you were alive). Not on a joint return. | |
| ira_basis | No | Optional: your Form 8606 basis (nondeductible traditional IRA contributions not yet recovered); that share of each traditional withdrawal and conversion is tax-free. Not with a per-owner traditional balance. | |
| annual_qcd | No | Yearly qualified charitable distribution from the traditional account, in today's dollars, counted against required minimum distributions. Default 0. | |
| birth_year | No | Year of birth, optional. Must match current_age: 2026 minus current_age, or 2025 minus current_age when this year's birthday is still to come (then every tax rule uses the age reached in each calendar year). Sets the RMD start age (73 if born 1951-1959, 75 if born 1960 or later). Default: 2026 minus current_age, stated in the result. | |
| dependents | No | Optional: up to 8 people you claim, each {age (at the end of 2026; negative = born later), student, disabled}. Each retirement year counts the qualifying children that year for the child tax credit (under 17), the credit for other dependents and the earned income credit, and gives them to the state return. | |
| spouse_age | No | Spouse's current age, for married filing jointly: sets the second aged deduction and Medicare surcharge. Default: the same as current_age, stated in the result. | |
| allocations | No | Percentages summing to 100: [US stocks, international stocks, bonds, real estate, cash]. Default [60,10,25,5,0]. | |
| birth_month | No | Month of birth, 1-12, optional. Times the half-year rules: the early-withdrawal penalty ends at 59 and a half, charitable distributions start at 70 and a half, Medicare starts in the birthday month. Default: not given, stated in the result. | |
| current_age | Yes | Current age of the primary person. | |
| bucket_years | No | Only with withdrawal_strategy bucket: years of spending held in the cash bucket, 1-10. | |
| pension_type | No | Whether the pension is private or a government (public) pension, which several states exempt from state income tax. Only affects the tax-aware tool. Default private, and the tax-aware result states it. | |
| return_model | No | How returns are generated. parametric (default): the forward-looking published assumptions. bootstrap: stationary block bootstrap of historical months. historical: replays real months from 1926 in order. The last two need a PRO licence; without one the engine runs parametric and the result says so. | |
| roth_balance | Yes | Roth IRA and Roth 401(k) balance today, in dollars. 0 if none. | |
| spouse_split | No | Married filing jointly with a state: whose IRA withdrawals, pension and Roth conversions they are on the state return: even (half each), filer (all the filer's) or spouse (all the spouse's). Arkansas, Delaware, Maryland, Minnesota, Missouri, North Dakota, Ohio and Virginia tax a couple by each spouse's own income, so there it can change the state tax; federal tax does not depend on it. Default on a joint return with a state: even (the spouse's age is then needed; when spouse_age is not given it is current_age), stated in the result. Not used off a joint return or without a state. | |
| ss_start_age | No | Age Social Security starts. Default 67. | |
| filing_status | Yes | Federal filing status: single, married filing jointly (mfj), married filing separately (mfs) or head of household (hoh). | |
| inflation_rate | No | Annual inflation as a percent, e.g. 2.5. Default 2.5. | |
| retirement_age | No | Age work income stops. Defaults to current age. | |
| returns_source | No | Which published return set to use (see list_return_assumption_sources). Default jpmorgan. | |
| aca_marketplace | No | Optional: the household buys marketplace (ACA) health coverage in the retirement years before Medicare. Each path's premium tax credit is figured each year by the federal engine's Form 8962 at that path's own income (no credit above 400% of the poverty line; Medicaid below 138% in expansion states), and the premium after the credit is funded each year and counted by the withdrawal-order search. Needs state. | |
| annual_spending | Yes | Planned yearly spending in today's dollars, after tax: what the household keeps. The engine withdraws enough each year to fund this plus that year's federal, state, Medicare-surcharge and penalty tax. | |
| life_expectancy | No | Age the plan must last until. Default 92. | |
| roth_conversion | No | The household's own Roth-conversion plan: a fixed amount per year between two ages. When given, the engine applies it on every path and searches withdrawal orders around it instead of searching its own conversion programmes. | |
| social_security | No | Yearly Social Security in today's dollars. Default 0 — and 0 is reported as an explicit assumption, not hidden. | |
| taxable_balance | Yes | Taxable brokerage and savings today, in dollars. 0 if none. The three balances together are the portfolio. | |
| cost_basis_ratio | No | Percentage of the taxable account that is cost basis, 0-100. Default 40, and the result says so when it is assumed. | |
| pension_start_age | No | Age the pension starts. Default 65. | |
| medicare_start_age | No | Age Medicare (and its IRMAA income surcharges) begins. Default 65. The year it begins is charged only for the months from the birthday month. | |
| itemized_deductions | No | Optional Schedule A amounts, in today's dollars a year: each year the engine adds that year's own state and local income tax (capped with the property tax by the SALT limit), takes gifts over 0.5% of AGI and medical costs over 7.5% of AGI, and itemizes when that gives the lower tax; otherwise the standard deduction. They are deductions only, assumed to be inside annual_spending already. Mortgage interest stays fixed in dollars until its end year, property tax rises 3.5% a year, giving with inflation, medical costs with inflation. Do not include QCDs in charitable_giving. Default: none, stated in the result. | |
| tax_exempt_interest | No | Yearly municipal-bond interest, which counts toward Social Security taxability and IRMAA income but is not itself taxed. Default 0. | |
| traditional_balance | Yes | Pre-tax retirement accounts today (traditional IRA, 401(k), 403(b)), in dollars. 0 if none. | |
| withdrawal_strategy | No | Spending rule. fixed (default): the planned amount, inflation-adjusted, every year. guyton-klinger: guardrails that cut or raise spending as the portfolio moves. vpw: variable percentage withdrawal. bucket: a cash reserve of bucket_years of spending. | |
| monthly_contribution | No | Monthly savings until retirement. Default 0. | |
| roth_contribution_basis | No | Optional: the part of roth_balance that is your own regular Roth IRA contributions (withdrawn first, tax-free). Giving it, roth_first_contribution_year or ira_basis turns on the Roth ordering and 5-year rules on Roth withdrawals (earnings before 59 1/2 or inside the 5-year clock are taxed, with the 10% additional tax before 59 1/2) and the Form 8606 pro-rata rule on traditional withdrawals and conversions. Default: all of roth_balance. | |
| roth_first_contribution_year | No | Optional: the first year you contributed to or converted into any Roth IRA (the 5-year clock), 1998-2026. Default: 2021 when roth_balance > 0. |