--- title: "Get Share Cohort" method: GET path: "/api/shares/{token}/cohort/{year}" tags: ["shares"] --- # Get Share Cohort `GET /api/shares/{token}/cohort/{year}` ## 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/shares/{token}/cohort/{year}` - Auth: none declared Materialize a single historical cohort for a shared scenario on demand. Per-cohort year-by-year ledgers are not persisted (see `historical-sampling-engine`). The handler re-runs the deterministic historical backtest from the share's stored config snapshot and returns the ledger for the requested cohort start year. 410 Gone is returned when the year is no longer in the cohort window — typically after the owner's edits shrank the historical range. ## Path parameters - `token` string, required - `year` integer, required ## Response `200` Successful Response - CohortResult - `start_year` integer, required - `is_failure` boolean, required - `depletion_year_index` integer - `yearly` YearDetailSchema[] - `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 ## 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)