---
title: "Get Scenario Detail"
method: POST
path: "/api/runs/{run_id}/scenario-detail"
tags: ["runs"]
---

# Get Scenario Detail

`POST /api/runs/{run_id}/scenario-detail`

## Request

- Base URL: `https://api.retirementlab.app` (the document declares no server; this is the origin it was published from)
- URL: `https://api.retirementlab.app/api/runs/{run_id}/scenario-detail`
- Auth: HTTP bearer

## Path parameters

- `run_id` integer, required

## Request body

- ScenarioDetailRequest
  - `scenario_index` integer, required

## Response `200`

Successful Response

- ScenarioDetailResponse
  - `scenario_index` integer, required
  - `is_failure` boolean, required
  - `years` YearDetailSchema[], required
    - `year` integer, required
    - `starting_balance` number, required
    - `starting_balances` YearDetailAccountBalances, required
      - `taxable` number, required
      - `tax_deferred` number, required
      - `tax_free` number, required
    - `portfolio_return_rate` number, required
    - `portfolio_return_amount` number, required
    - `income` YearDetailIncomeItem[], required
      - `source` string, required
      - `amount` number, required
    - `income_total` number, required
    - `expenses` YearDetailExpenseItem[], required
      - `description` string, required
      - `amount` number, required
    - `expenses_total` number, required
    - `investment_yield` number, required
    - `withdrawals` YearDetailWithdrawals, required
      - `taxable` number, required
      - `tax_deferred` number, required
      - `tax_free` number, required
      - `total` number, required
      - `taxable_principal` number
      - `taxable_yield_consumed` number
    - `capital_gains_realized` number, required
    - `taxes` YearDetailTaxes, required
      - `income` number, required
      - `investment_income` number, required
      - `capital_gains` number, required
      - `wealth` number, required
      - `surcharges` number, required
      - `total` number, required
      - `dual_tax` YearDetailDualTax
        - `residency_tax` number, required
        - `citizenship_tax` number, required
        - `ftc_applied` number, required
        - `net_tax` number, required
        - `residency_income_tax` number
        - `residency_investment_income_tax` number
        - `residency_capital_gains_tax` number
        - `residency_wealth_tax` number
        - `residency_surcharges` number
        - `citizenship_income_tax` number
        - `citizenship_investment_income_tax` number
        - `citizenship_capital_gains_tax` number
        - `citizenship_wealth_tax` number
        - `citizenship_surcharges` number
        - `gross_french_pfu_by_component` object
        - `article24_credit_by_component` object
        - `net_french_portfolio_tax` number
        - `article24_eligibility_status` string
      - `early_withdrawal_penalty` number
      - `englobamento` YearDetailEnglobamento: Per-year disclosure of Portugal's englobamento decision. ``selection`` is the user's preference (``"auto"``, ``"always"``, or ``"never"``); ``applied`` is which option the policy actually used — ``"englobamento"`` (progressive aggregation) or ``"autonomous"`` (28% flat). The two ``*_tax`` fields are the alternatives so the year detail can show what the other choice would have cost.
        - `selection` 'auto' | 'always' | 'never', required
        - `applied` 'englobamento' | 'autonomous', required
        - `autonomous_tax` number, required
        - `englobamento_tax` number, required
      - `reconciliation` YearDetailTaxReconciliation: Country-specific reconciliation surfaced for Canada (issue #662) so the year detail can show the dividend gross-up, dividend tax credits, capital-gains inclusion, and ordinary interest treatment alongside the headline tax.
        - `country` string, required
        - `yield_treatment` string, required
        - `yield_treatment_label` string, required
        - `used_default_assumption` boolean, required
        - `lines` YearDetailTaxReconciliationLine[], required
          - `key` string, required
          - `label` string, required
          - `amount` number, required
      - `taxable_securities_gross_proceeds` number
      - `proceeds_based_tax` number
      - `applied_simplifications` string[]
    - `surplus_deposited` number, required
    - `ending_balance` number, required
    - `ending_balances` YearDetailAccountBalances, required
      - `taxable` number, required
      - `tax_deferred` number, required
      - `tax_free` number, required
    - `cumulative_inflation` number, required
    - `asset_returns` AssetReturnItemSchema[]
      - `asset_class_id` string, required
      - `label` string, required
      - `weight` number, required
      - `return_rate` number, required
      - `return_amount` number, required
    - `rebalancing` RebalancingTradeSchema[]
      - `asset_class_id` string, required
      - `name` string, required
      - `pre_weight` number, required
      - `target_weight` number, required
      - `trade_amount` number, required
    - `withdrawal_strategy_name` string
    - `withdrawal_target` number
    - `withdrawal_floor` number
    - `withdrawal_ceiling` number
    - `withdrawal_baseline` number
    - `guardrail_hit` string
    - `regime` string
    - `exit_tax` YearDetailExitTaxLine: Exit-tax line for years where a relocation triggers an expatriation / deemed-disposition charge. Populated by the per-country exit-tax engine (see ``specs/exit-tax-engine.md``); omitted when no exit tax fires.
      - `amount` number, required
      - `description` string
    - `expense_change` YearDetailExpenseChange: Year where the active baseline expense changes (baseline-adjustment event or a relocation expense adjustment fires). Carries the prior and new amounts so the ledger can render a narrative change line.
      - `reason` string, required
      - `prior_amount` number, required
      - `new_amount` number, required
    - `rmds` YearDetailRmdLine[]
      - `amount` number, required
      - `account` string
      - `age` integer
      - `account_label` string
      - `wrapper_id` string
      - `bucket` string
      - `access_reason` string
    - `roth_conversions` YearDetailRothConversion[]
      - `amount` number, required
      - `description` string
      - `account_label` string
      - `wrapper_id` string
      - `bucket` string
      - `access_reason` string
    - `withdrawal_sources` YearDetailAccountSourceLine[]
      - `account_label` string
      - `wrapper_id` string
      - `bucket` string, required
      - `amount` number, required
      - `access_reason` string
    - `early_withdrawal_penalty` YearDetailEarlyWithdrawalPenaltyLine: US 10% additional federal tax on pre-59½ tax-deferred distributions. See ``specs/us-early-distribution-penalty.md``.
      - `amount` number, required
    - `harvested_loss` number
    - `puma_csm` YearDetailPumaCsm
      - `eligibility_status` string, required
      - `amount` number, required
      - `adults` YearDetailPumaCsmAdult[]
        - `person` string
        - `relationship` string, required
        - `liable` boolean, required
        - `reason` string, required
        - `assessment_income` number, required
        - `professional_income` number, required
        - `coverage_fraction` number, required
        - `amount` number, required
  - `config_summary` ScenarioDetailConfigSummary, required
    - `horizon` integer, required
    - `initial_year` integer, required
    - `country` string, required
    - `currency` string, required
    - `inflation_rate` number, required
  - `early_distribution_penalty_disclosure_active` boolean

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/retirementlab/apis/income-simulator-api.md) · [All operations](https://skmtc.dev/retirementlab/apis/income-simulator-api/llms.txt) · [OpenAPI document](https://skmtc.dev/retirementlab/apis/income-simulator-api/revisions/b0f00a0333fd?raw)