---
title: "Required savings to fund a target retirement income"
method: POST
path: "/v1/retirement/savings-target"
tags: ["Retirement"]
---

# Required savings to fund a target retirement income

`POST /v1/retirement/savings-target`

## Request

- Base URL: `https://api.numeratica.com`
- URL: `https://api.numeratica.com/v1/retirement/savings-target`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

The inverse of an accumulation projection: given a target retirement income, other income (SS/pension), and return/inflation assumptions, returns the required nest egg, the annual/monthly saving needed from today, and the gap versus the current trajectory. Works in real (today's) dollars. For a success-probability target, pair with the Monte Carlo endpoint. Deterministic.

## Request body

- SavingsTargetRequest
  - `annual_fee_rate` number, double: All-in annual cost drag as a decimal (0.01 = 1%): advisory fee plus fund expense ratios, applied as a reduction to the expected return. Omitted or 0 means the projection is GROSS of fees, which leaves result_id unchanged. Costs compound: a 1% load moves long-horizon outcomes by a large margin (see the Concepts page).
  - `current_age` integer, required
  - `retirement_age` integer, required
  - `end_age` integer, required
  - `target_annual_income` number, required: Today's dollars.
  - `other_income` number: SS/pension at retirement, today's dollars.
  - `current_savings` number
  - `expected_return` number, required: Nominal.
  - `inflation` number
  - `withdrawal_rate` number: Optional; adds a rule-of-thumb nest egg (gap / rate).
  - `success_probability_target` number: Optional. When set, runs a Monte Carlo search for the smallest annual saving meeting this success rate.
  - `return_volatility` number: Real-return volatility for the Monte Carlo search.
  - `num_simulations` integer: Required (> 0) when success_probability_target is set.
  - `seed` integer: Optional; generated and echoed when a target is set.

## Response `200`

Savings analysis

- SavingsTargetResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` SavingsTargetRequest
    - `annual_fee_rate` number, double: All-in annual cost drag as a decimal (0.01 = 1%): advisory fee plus fund expense ratios, applied as a reduction to the expected return. Omitted or 0 means the projection is GROSS of fees, which leaves result_id unchanged. Costs compound: a 1% load moves long-horizon outcomes by a large margin (see the Concepts page).
    - `current_age` integer, required
    - `retirement_age` integer, required
    - `end_age` integer, required
    - `target_annual_income` number, required: Today's dollars.
    - `other_income` number: SS/pension at retirement, today's dollars.
    - `current_savings` number
    - `expected_return` number, required: Nominal.
    - `inflation` number
    - `withdrawal_rate` number: Optional; adds a rule-of-thumb nest egg (gap / rate).
    - `success_probability_target` number: Optional. When set, runs a Monte Carlo search for the smallest annual saving meeting this success rate.
    - `return_volatility` number: Real-return volatility for the Monte Carlo search.
    - `num_simulations` integer: Required (> 0) when success_probability_target is set.
    - `seed` integer: Optional; generated and echoed when a target is set.
  - `result` object
    - `income_gap` number: Annual income the portfolio must fund (today's dollars).
    - `required_nest_egg` number: PV of the income gap over retirement.
    - `required_nest_egg_by_rule` number: income_gap / withdrawal_rate (only when set).
    - `required_annual_savings` number
    - `required_monthly_savings` number
    - `projected_without_saving` number: FV of current savings, no new contributions.
    - `shortfall_vs_trajectory` number: Required nest egg minus the above (0 if on track).
    - `on_track` boolean
    - `monte_carlo` object: Present only when success_probability_target is set.
      - `success_probability_target` number
      - `required_annual_savings_mc` number: Smallest annual saving whose simulated success rate meets the target.
      - `required_monthly_savings_mc` number
      - `achieved_success_probability` number: Success rate at the reported saving.
      - `num_simulations` integer
      - `seed` integer
  - `disclaimer` string

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key.
- `405`: Method not allowed
- `429`: The key's per-minute request budget is exceeded. Retry after the delay in the Retry-After header.
- `503`: A dependency (e.g. the key store) is temporarily unavailable, or the request exceeded its compute deadline. Retryable.

---

[API](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api.md) · [All operations](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/revisions/075bcfbd1ebf?raw)