Skip to content
Patrimoine
v9.1.0

Simulation Endpoint

GET
/api/v1/reports/simulation
curl --request GET \
  --url https://example.com/api/v1/reports/simulation

A seeded Monte Carlo retirement simulation in today’s money over a fixed 5,000 paths.

The balance, spending and savings are the financial independence figures; the balance grows until the retirement age, then the spending is drawn down for the retirement length. The same seed and inputs always give the same result. Volatility is a percent. Read-only.

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
current_age
Any of:
integer
>= 18 <= 100
retirement_age
Any of:
integer
>= 18 <= 100
retirement_length
Any of:
integer
>= 5 <= 60
volatility
Any of:
number
<= 40
seed
Any of:
integer
<= 2147483647

Responses

Section titled “Responses”

200

Section titled “200”

Successful Response

Media typeapplication/json
SimulationOut

A seeded retirement simulation. success_rate is the percent of paths still positive at the end of the last retirement year; it and years are empty unless status is ok.

object
status
required
Status
string
Allowed values: ok no_history no_accounts no_spending
currency
required
Currency
string
paths
required
Paths
integer
seed
required
Seed
integer
current_age
required
Current Age
integer
retirement_age
required
Retirement Age
integer
end_age
required
End Age
integer
success_rate
required
Any of:
string
years
required
Years
Array<object>
SimulationYearOut

The balance percentiles at the start of one age, in today’s money.

object
age
required
Age
integer
p10
required
P10
string
p25
required
P25
string
p50
required
P50
string
p75
required
P75
string
p90
required
P90
string
inputs
required
SimulationInputsOut

The inputs the simulation actually used; rates are in percent.

object
starting_balance
required
Starting Balance
string
annual_spending
required
Annual Spending
string
annual_spending_source
required
Annual Spending Source
string
Allowed values: ledger override
monthly_savings
required
Monthly Savings
string
real_return
required
Real Return
string
volatility
required
Volatility
string
retirement_length
required
Retirement Length
integer
account_ids
required
Account Ids
Array<integer>
accounts_source
required
Accounts Source
string
Allowed values: override saved default
history_months
required
History Months
integer
short_history
required
Short History
boolean
savings_non_positive
required
Savings Non Positive
boolean
balance_as_of
required
Any of:
string format: date
annual_spending_excluded
Annual Spending Excluded
string
default: 0
warnings
required
FireWarningsOut

Report warnings plus the accounts left out of the starting balance for a missing rate.

object
missing_rate_currencies
Missing Rate Currencies
Array<string>
default:
excluded_transactions
Excluded Transactions
integer
0
excluded_accounts
Excluded Accounts
integer
0

Example 

{
  "status": "ok",
  "inputs": {
    "annual_spending_source": "ledger",
    "accounts_source": "override",
    "annual_spending_excluded": "0"
  },
  "warnings": {
    "missing_rate_currencies": [],
    "excluded_transactions": 0,
    "excluded_accounts": 0
  }
}

422

Section titled “422”

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
input
Input
ctx
Context
object

Example generated

{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}