---
title: "Project savings to retirement across account types"
method: POST
path: "/v1/retirement/accumulation-projection"
tags: ["Retirement"]
---

# Project savings to retirement across account types

`POST /v1/retirement/accumulation-projection`

## Request

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

Deterministic accumulation across multiple accounts with contribution escalation and an employer match, returning the projected balance by account and total (nominal + real). With num_simulations > 0 it reuses the Monte Carlo return model to add stochastic ending-total percentile bands. Deterministic given a seed.

## Request body

- AccumulationRequest
  - `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).
  - `accounts` object[], required
    - `name` string, required
    - `current_balance` number
    - `annual_contribution` number
    - `receives_match` boolean: The account the employer match is deposited into (default: the first).
    - `contribution_cap` number: Caps the escalated annual contribution (the 'escalate to a limit' mode); 0 = uncapped.
  - `escalation_rate` number: Annual % increase in contributions.
  - `employer_match_rate` number: Match on total employee contributions.
  - `employer_match_limit` number: Annual $ cap on the match (0 = uncapped).
  - `expected_return` number: Required unless a glide_path is supplied.
  - `return_volatility` number: For the optional stochastic bands.
  - `inflation` number
  - `years` integer, required
  - `num_simulations` integer: 0 = deterministic only.
  - `seed` integer: Optional; generated and echoed when simulating.
  - `current_age` integer: Anchors the glide path: the return for projection year y is taken at age current_age+y. Required when glide_path is supplied.
  - `glide_path` object[]: Optional age-varying return assumptions (same waypoint model as the Monte Carlo engine), overriding the scalar expected_return/ return_volatility. Strictly ascending age order; when provided, expected_return is not required.
    - `age` integer, required
    - `expected_return` number, required
    - `return_volatility` number, required

## Response `200`

Accumulation projection

- AccumulationResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` AccumulationRequest
    - `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).
    - `accounts` object[], required
      - `name` string, required
      - `current_balance` number
      - `annual_contribution` number
      - `receives_match` boolean: The account the employer match is deposited into (default: the first).
      - `contribution_cap` number: Caps the escalated annual contribution (the 'escalate to a limit' mode); 0 = uncapped.
    - `escalation_rate` number: Annual % increase in contributions.
    - `employer_match_rate` number: Match on total employee contributions.
    - `employer_match_limit` number: Annual $ cap on the match (0 = uncapped).
    - `expected_return` number: Required unless a glide_path is supplied.
    - `return_volatility` number: For the optional stochastic bands.
    - `inflation` number
    - `years` integer, required
    - `num_simulations` integer: 0 = deterministic only.
    - `seed` integer: Optional; generated and echoed when simulating.
    - `current_age` integer: Anchors the glide path: the return for projection year y is taken at age current_age+y. Required when glide_path is supplied.
    - `glide_path` object[]: Optional age-varying return assumptions (same waypoint model as the Monte Carlo engine), overriding the scalar expected_return/ return_volatility. Strictly ascending age order; when provided, expected_return is not required.
      - `age` integer, required
      - `expected_return` number, required
      - `return_volatility` number, required
  - `result` object
    - `accounts` object[]
      - `name` string
      - `ending_balance` number
      - `total_contributed` number
      - `employer_match` number
    - `ending_total` number: Nominal.
    - `ending_total_real` number: Deflated to today's dollars.
    - `total_employee_contributions` number
    - `total_employer_match` number
    - `percentiles` object: Stochastic ending-total bands (only when num_simulations > 0).
      - `p10` number
      - `p25` number
      - `p50` number
      - `p75` number
      - `p90` number
    - `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)