Endpoint POST /api/simulation/simulate
Runs a Monte Carlo simulation using the provided financial profile, user inputs, and goal parameters. The simulation generates thousands of possible future scenarios to calculate success probability and outcome distributions.
Request Body The request body must be a valid SimulationRequest object.
Complete financial profile containing current financial state. Show FinancialProfile Properties
Total liquid assets (checking + savings).
Total outstanding loan principal.
Monthly loan payment obligations.
Total estimated monthly spending.
Breakdown of spending by category (category name to amount mapping).
Spending volatility metric (0.0 - 0.3).
User-specific information affecting simulation parameters. Show UserInputs Properties
User’s monthly income (used for simulation calculations).
Risk tolerance level. Must be one of: "low", "medium", "high".
Financial goal parameters for the simulation. Target dollar amount to achieve.
Number of months until goal deadline.
Type of financial goal (e.g., “retirement”, “house”, “emergency_fund”).
Optional parameters to control simulation execution. Show SimulationParams Properties
Number of Monte Carlo iterations to run. Defaults to 100,000. Higher values increase accuracy but take longer.
Response Returns detailed simulation results including success probability and outcome distributions.
Probability (0.0 - 1.0) of achieving the specified goal within the timeline.
Median portfolio value at the goal timeline (50th percentile).
Portfolio value at various percentiles of the outcome distribution. 10th percentile outcome (pessimistic scenario).
50th percentile outcome (median).
90th percentile outcome (optimistic scenario).
Mean (average) portfolio value across all simulations.
Standard deviation of outcomes, indicating variability.
Minimum portfolio value observed across all simulations.
Maximum portfolio value observed across all simulations.
Simulation assumptions used in the Monte Carlo model. Show Assumptions Properties
Expected annual investment return rate.
Standard deviation of annual returns (volatility).
Annual inflation rate assumption.
Volatility in inflation rate.
Expected annual salary raise percentage.
Frequency of salary raises (e.g., “annual”).
promotionProbabilitySemiAnnual
Probability of promotion every 6 months.
Expected salary increase from promotion.
emergencyProbabilityMonthly
Probability of financial emergency each month.
Range of emergency expense amounts.
Volatility in monthly income.
Volatility in monthly expenses.
Example Request curl -X POST "https://api.drift.example/api/simulation/simulate" \ -H "Content-Type: application/json" \ -d '{ "financialProfile": { "liquidAssets": 15420.50, "creditDebt": 3250.00, "loanDebt": 28500.00, "monthlyLoanPayments": 425.00, "monthlyIncome": 6500.00, "monthlyBills": 850.00, "monthlySpending": 4120, "spendingByCategory": { "Grocery": 450.75, "Restaurants": 320.50, "Gas": 180.00 }, "spendingVolatility": 0.18 }, "userInputs": { "monthlyIncome": 6500, "age": 32, "riskTolerance": "medium" }, "goal": { "targetAmount": 50000, "timelineMonths": 36, "goalType": "house_downpayment" }, "simulationParams": { "nSimulations": 100000 } }'
Example Response { "successProbability" : 0.73 , "medianOutcome" : 52340.25 , "percentiles" : { "p10" : 38200.50 , "p25" : 45100.75 , "p50" : 52340.25 , "p75" : 59800.00 , "p90" : 68500.50 }, "mean" : 53125.80 , "std" : 12450.30 , "worstCase" : 22100.00 , "bestCase" : 92300.75 , "assumptions" : { "annualReturnMean" : 0.07 , "annualReturnStd" : 0.15 , "inflationRate" : 0.03 , "inflationVolatility" : 0.01 , "annualRaiseMean" : 0.03 , "annualRaiseFrequency" : "annual" , "promotionProbabilitySemiAnnual" : 0.05 , "promotionRaiseMean" : 0.10 , "emergencyProbabilityMonthly" : 0.02 , "emergencyAmountRange" : "500-3000" , "incomeVolatility" : 0.05 , "expenseVolatility" : 0.18 } }
Error Responses 500 Internal Server Error { "error" : "Failed to run simulation" }
Usage Notes
Success probability above 0.70 (70%) is generally considered a good likelihood of achieving the goal
The simulation accounts for investment returns, inflation, income volatility, expense volatility, and random life events
Higher nSimulations values provide more accurate results but increase computation time
Risk tolerance affects the investment return assumptions used in the simulation
The assumptions object in the response shows the exact parameters used for transparency