Goals
Create, track, and project financial goals.
create_goal
Section titled “create_goal”Create a financial goal with specified targets.
| Parameter | Type | Default | Description |
|---|---|---|---|
name |
string | required | Goal name (1-200 characters) |
goal_type |
string | required | Kind of financial goal being created. |
importance |
float | required | Success probability target (0.01-0.99, e.g., 0.90 = 90% confidence) |
target_amount_cents |
int | null | Target amount in cents (for goals with a fixed savings target) |
target_date |
string | null | Target date in YYYY-MM-DD format (optional) |
target_date_flexibility |
string | null | How firm the target date is. |
contribution_amount_cents |
int | null | Fixed monthly contribution in cents |
contribution_percentage |
float | null | Contribution as % of income (e.g., 0.15 = 15%) |
contribution_schedule |
object | null | A monthly contribution that starts, stops or grows, in place of contribution_amount_cents / contribution_percentage (pass none of those with it): {“monthly_amount_cents”: int, “start_date”?: “YYYY-MM-DD”, “end_date”?: “YYYY-MM-DD”, “annual_growth_rate”?: float, “real_terms”?: bool}. Both dates are inclusive and optional. For $1,293/mo from Sep 2026 through Apr 2027: {“monthly_amount_cents”: 129300, “start_date”: “2026-09-01”, “end_date”: “2027-04-30”}. Amounts are nominal (face value) unless real_terms is true, which makes them today’s dollars, grossed up by the projection’s inflation. Unknown or mistyped fields are rejected. |
months_expenses |
int | null | Number of months of expenses to save (for emergency_fund goals) |
status |
string | "active" |
Lifecycle status of the goal. |
tax_advantaged |
bool | false |
Prefer tax-advantaged accounts for this goal |
notes |
string | null | Additional notes about the goal |
description |
string | null | Optional longer description of the goal |
target_price_level |
object | null | Price level of target_amount_cents and of every payout_schedule amount. Omit for today’s dollars (real purchasing power at creation). For future nominal dollars, such as quoted future tuition bills: {“adjustment”: “nominal”}. For a specific reference purchasing power: {“adjustment”: “real”, “reference_year”: 2026, “reference_month”: 1}. |
payout_schedule |
list | null | Scheduled payouts for multi-year goals (e.g. education), each {“payout_date”: “YYYY-MM-DD”, “amount_cents”: int}. Amounts are in target_price_level’s frame (today’s dollars when it is omitted), so set target_price_level to {“adjustment”: “nominal”} for face-value future bills. For tuition, prefer the generator arguments (beneficiary_id, cost_preset or annual_cost_today_cents, …) over building rows by hand; pass one or the other, never both. |
deposit_schedule |
list | null | Dated one-off deposits into the goal, such as a bonus, each {“deposit_date”: “YYYY-MM-DD”, “amount_cents”: int > 0}, sorted by date. Amounts are nominal (face value on that date), whatever target_price_level says. Deposits on one date add up. Projections ignore a deposit before today (already in the balance) and note any beyond their horizon. Don’t also enter the same money as income linked to the goal, or it counts twice. |
beneficiary_id |
string | null | Generator: id of the student in state_json’s household (usually a dependent). Their date_of_birth dates the school years. Passing any generator argument generates the payout_schedule instead of taking rows; beneficiary_id, state_json and exactly one of cost_preset or annual_cost_today_cents are then required. |
state_json |
object | null | Generator: the user state document, used only to look up beneficiary_id. |
annual_cost_today_cents |
int | null | Generator: one school year’s full cost at today’s prices, in cents. Use it for a cost the user knows, such as their expected net cost; otherwise pass cost_preset. |
cost_preset |
string | null | Generator: a named school-year cost instead of annual_cost_today_cents: ‘public_in_state’, ‘public_out_of_state’ or ‘private_nonprofit’ (four-year colleges). Each is College Board’s published cost of attendance (tuition, fees, housing and food) before aid. The response’s generated_schedule.cost_preset names the figure, its source and publication year. |
start_age |
int | null | Generator: the age the student reaches by the end of the first payout’s month (default 18). The first payout is the first start_month in or after the month they turn start_age: in the year they turn start_age if born in or before start_month, otherwise the year after. |
years |
int | null | Generator: number of school years to pay (default 4). |
education_inflation_premium |
float | null | Generator: annual tuition growth ABOVE inflation, as a decimal (0.02 = 2%). Omit for the 2% long-run default; the response then says the default was used. |
start_month |
int | null | Generator: month (1-12) each school year’s payout falls in (default 8). |
precondition_goal_id |
string | null | ID of a goal that must reach precondition_threshold before this goal is funded |
precondition_threshold |
float | null | Fraction (0.0-1.0) of the precondition goal that must be met first |
Returns the created goal as JSON including auto-generated ID and validation results.
get_goal_progress
Section titled “get_goal_progress”Calculate current progress toward a goal — today’s balance only, no projection.
| Parameter | Type | Default | Description |
|---|---|---|---|
goal_json |
object | required | Goal as a JSON dict. Required keys: name, goal_type, importance (0.01-0.99); “emergency_fund” goals also require months_expenses. current_balance_cents is optional (defaults to 0) but should be set to the goal’s funded balance (the linked account’s balance) — the goal’s own current_balance_cents is often 0 because funding is account-derived. |
state_json |
object | null | Optional full user state JSON. When its accounts include one or more accounts whose goal_id matches goal_json.id, their integer balance_cents values are summed and used as the goal’s funded balance; otherwise goal_json.current_balance_cents is used. |
Returns progress percentage, remaining amount, and completion status. For a goal with payouts still ahead, progress is today’s balance divided by the plain sum of the payouts still ahead (progress_basis “remaining_payouts”); otherwise it is the balance divided by the target (progress_basis “target_amount”). For whether the plan will cover the payouts, use project_goal_progress. Pass state_json to derive the funded balance from accounts linked to the goal’s id; otherwise the goal_json current_balance_cents value is used.
project_goal_progress
Section titled “project_goal_progress”Project goal progress forward with compound growth.
| Parameter | Type | Default | Description |
|---|---|---|---|
goal_json |
object | required | Goal as a JSON dict. Required keys: name, goal_type, importance (0.01-0.99); “emergency_fund” goals also require months_expenses. current_balance_cents is optional (defaults to 0) but should be set to the goal’s funded balance (the linked account’s balance). With state_json, the funded balance is resolved from accounts linked to goal_json.id; without it, passing the raw goal (often 0) projects from $0. |
state_json |
object | null | Optional full user state JSON. When its accounts include one or more accounts whose goal_id matches goal_json.id, their integer balance_cents values are summed and used as the projection’s starting funded balance; otherwise goal_json.current_balance_cents is used. |
annual_return_rate |
float | 0.07 |
Expected annual return rate (e.g., 0.07 = 7%) |
annual_volatility |
float | 0.0 |
Annual return volatility (standard deviation) as a decimal (e.g., 0.15 = 15%). When > 0, the projection spreads into a percentile band (p10/p25/p50/p75/p90) so return uncertainty is visible: p10 < p50 < p90, and the median (p50) reflects volatility drag (it sits below the zero-volatility expected path). Leave 0 for a single deterministic figure. |
months_ahead |
int | null | Number of months to project forward. If omitted, the projection runs to the goal’s own horizon: its last scheduled payout for a goal with payouts still ahead (or target_date if later), else its target_date (or today if it has none), so the result answers the question the goal defines rather than an arbitrary horizon. Pass a value only to override with a fixed horizon. |
monthly_income_cents |
int | 0 |
Caller’s monthly income in cents. Only used for goals funded by contribution_percentage (PERCENTAGE_INCOME); ignored otherwise. Leave 0 if the goal has no income-percentage contribution. |
inflation |
float | 0.0 |
Annual inflation rate as decimal (e.g., 0.03 = 3%). When > 0, a real-terms target is inflated to the projection date’s nominal value before progress is computed, and a real-terms goal’s payout_schedule is inflated to nominal at each payout’s month, so payout_coverage is nominal. remaining_payouts_cents stays in the goal’s target_price_level frame; each block names its frame. |
Returns: goal_id, goal_name, balance_source, current_balance_cents, current_balance_dollars, projection_date, months_ahead, projection_basis, annual_return_rate, and annual_volatility, and more.
project_goal_series
Section titled “project_goal_series”Project a goal’s balance and progress as a year-by-year (or N-month) series in one call.
| Parameter | Type | Default | Description |
|---|---|---|---|
goal_json |
object | required | Goal as a JSON dict. Required keys: name, goal_type, importance (0.01-0.99); “emergency_fund” goals also require months_expenses. current_balance_cents is optional (defaults to 0) but should be set to the goal’s funded balance (the linked account’s balance). With state_json, the funded balance is resolved from accounts linked to goal_json.id; without it, passing the raw goal (often 0) projects from $0. |
state_json |
object | null | Optional full user state JSON. When its accounts include one or more accounts whose goal_id matches goal_json.id, their integer balance_cents values are summed and used as the series’ starting funded balance; otherwise goal_json.current_balance_cents is used. |
annual_return_rate |
float | 0.07 |
Expected annual return rate (e.g., 0.07 = 7%) |
annual_volatility |
float | 0.0 |
Annual return volatility (standard deviation) as a decimal. When > 0, each point spreads into a percentile band (p10/p25/p50/p75/p90); leave 0 for a single deterministic path per point. |
months_ahead |
int | null | Horizon to project through. If omitted, runs to the goal’s own horizon: its last scheduled payout for a goal with payouts still ahead (or target_date if later), else its target_date (or today if it has none). The series is sampled from today to this horizon. |
step_months |
int | 12 |
Sampling cadence in months (default 12 = annual points). Use 1 for a monthly series. Today (month 0) and the exact horizon are always included. |
monthly_income_cents |
int | 0 |
Caller’s monthly income in cents. Only used for goals funded by contribution_percentage (PERCENTAGE_INCOME); ignored otherwise. |
inflation |
float | 0.0 |
Annual inflation rate as decimal (e.g., 0.03 = 3%). When > 0, a real-terms target is inflated to each point’s nominal value before progress is computed, and a real-terms goal’s payout_schedule is inflated to nominal at each payout’s month. remaining_payouts_cents stays in the goal’s target_price_level frame, named by remaining_payouts_price_level. |
Returns: goal_id, goal_name, balance_source, annual_return_rate, annual_volatility, step_months, point_count, target_amount_cents, target_amount_dollars, and series, and more.
required_monthly_cashflow
Section titled “required_monthly_cashflow”Calculate the monthly contribution needed to reach a goal.
| Parameter | Type | Default | Description |
|---|---|---|---|
target_amount_cents |
int | required | Target goal amount in cents |
time_horizon_months |
int | required | Number of months until target date |
initial_balance_cents |
int | 0 |
Current savings toward goal in cents |
annual_return_rate |
float | 0.07 |
Expected annual return rate (e.g., 0.07 = 7%) |
inflation |
float | 0.0 |
Annual inflation rate as decimal (e.g., 0.03 = 3%). When > 0, the target is assumed to be in today’s dollars and is inflated to the target date’s nominal value before solving. |
Returns: target_amount_cents, target_amount_dollars, initial_balance_cents, initial_balance_dollars, time_horizon_months, annual_return_rate, inflation, inflation_adjusted_target_cents, inflation_adjusted_target_dollars, and cashflow_cents, and more.