Returns the balance of up to 100 accounts over one window: one series per account, in the account's own currency, with one point per bucket, each point labelled recorded or estimated. Name the accounts with account_group_keys, the account_group_key (uagr_…) of each account accounts__list_financial_accounts returns; a duplicate key is read once. An empty series list comes with empty_state_message, which names the next step. Name the window with range, or with from and to (inclusive yyyy-MM-dd dates spanning at most 14000 days); with neither, the window is one_year ending today (UTC). Granularity weekly (the default here) cuts one bucket per ISO week; ask for daily for one per day or monthly for one per calendar month. Each point is the balance at its bucket_end, an instant, and bucket_time_zone_id names the zone every bucket was cut in. A point's kind is recorded (source provider, a balance the account's provider reported, or manual, one the user stated) or estimated (source transaction_derived, a balance the balance backfill of a manually tracked account derived from its transactions, or extrapolated, computed when read from a provider account's recorded balances moved by its transactions); always present an estimated point as an estimate. A bucket that holds a recorded balance reads that balance. observed_in_bucket false means the bucket holds none of the point's own evidence (a recorded balance, a stored derived balance, or for an extrapolated point a transaction dated in it), so its value was carried into it. sources recorded_and_estimated (the default) serves recorded balances and, in the buckets no recorded balance holds, estimates; recorded_only serves no estimate, and a bucket with no reading of its own repeats the last recorded balance with observed_in_bucket false. carry_in is the account's recorded balance as the window opens, null when none is recorded by then; the points start at the first bucket with a value, and nothing is invented for the buckets before it. estimate_basis names the estimate source a series used (none, transaction_derived or extrapolated). estimates_withheld_for_liability true marks a liability whose backfill-derived balances are not served, because that derivation moves an amount owed the wrong way; its series holds recorded balances only, and its estimate_note says so. Report each series in its own currency (its upper-case ISO 4217 code, or Unknown when the account has no currency on record), and never add series of different currencies. The user's plan can limit how far back estimates reach: when history_window_message is present, estimates before history_window_floor_date were withheld, and history_window_floor_degraded true means the plan could not be confirmed, so the withholding is not the plan's own limit; recorded balances are never withheld. is_investment marks an investment account, whose series is its balance only, not its portfolio value; when a series carries portfolio_value_tool, call holdings__get_holding_value_series with scope account_group and that series' account_group_key for its portfolio value over time. Live accounts are read by default; to read a paper or scenario account, name every mode to read in include_simulation_modes (for example ["live", "paper"]). included_simulation_modes echoes the modes read and excluded_account_count counts the requested accounts the mode filter left out. left_out_keys lists every requested key with no series and why: not_found, no active account of the user's has the key (it is mistyped, another kind of key, an account that is not active, or one whose connection was disconnected; accounts__check_account_balance with a not-found key says whether its account's connection was disconnected, and if it was, reconnect it via connections__connect_bank_account to restore balances on a plan that includes live data sources; on a plan that includes none, accounts__check_account_balance says so and what to do instead); excluded_simulation_mode, its mode is not among those read; not_visible, the user's plan or the user's own choice hides the account, and its current balance is hidden the same way (accounts__check_account_balance says which); no_balance_surface, its provider reports no balance; no_balance_history, no balance is known for it in the window, and none is invented; estimates_withheld_by_history_window, only estimates reached the window and the history window withheld them all (history_window_message says from which date and why); estimates_withheld_for_liability, a liability whose only values in the window are backfill-derived balances, which are not served. One call reads at most 36600 points (accounts times buckets); a larger read is refused with words naming a coarser granularity, a shorter window or fewer accounts. A call naming more than 100 distinct keys is refused; read the others in further calls.
Parameters
The account_group_key (uagr_…) of each account to read, as accounts__list_financial_accounts returns it: between 1 and 100 distinct keys, matched exactly; a duplicate is read once. A key that names no account of the user's is answered in left_out_keys, never as an error. An empty series list comes with empty_state_message, which names the next step.
The first date of the window, inclusive, as yyyy-MM-dd. Send it with to, or alone; omit it for the one_year window that ends on to. The window spans at most 14000 days. Format: yyyy-MM-dd.
The size of each bucket: weekly (the default) cuts one per ISO week, monthly one per calendar month and daily one per day. Each point is the balance at its bucket_end. A daily read of many accounts over a long window can pass the 36600-point limit of one call; a coarser granularity keeps it inside. Default: `weekly`.
The kinds of account to read: 'live' is real money, 'paper' is a broker's practice account and 'scenario' is a user's hypothetical. Send several to read more than one, for example ["live", "paper"]. Omit to read live accounts only (the default, ["live"]); a list names at least one mode. included_simulation_modes echoes the modes read and excluded_account_count counts the requested accounts left out.
A named window ending today (UTC): one_day and five_days are the last one and five calendar days; one_month, three_months, six_months, one_year and five_years are calendar spans; year_to_date starts on 1 January; max starts at the earliest balance on record among the accounts read (an estimate on record dated before the user's history window counts from that window's floor, and history_window_applied says so when that moves the start), at most 14000 days back. Send range alone, or from and to alone. With neither range nor dates, the window is one_year.
sources recorded_and_estimated (the default) serves recorded balances and, in the buckets no recorded balance holds, estimates; recorded_only serves no estimate, and a bucket with no reading of its own repeats the last recorded balance with observed_in_bucket false.
The last date of the window, inclusive, as yyyy-MM-dd, read as a UTC calendar date. Omit it for today; a later date reads as today. Format: yyyy-MM-dd.
.svg)
.svg)
.svg)
