Returns live runway Needed for each non-deleted box (max 30). When status is ready, includes expectedInAccountToday (opening, includes today’s bills) and expectedAfterTodaysBills (closing). Other statuses (undatedExpenses, missingCreditCycleEndDay, noPlannedExpenses) omit amounts. Optional asOfDate (yyyy-MM-dd, default UTC today) is a current-plan reprojection, not Reports history — use get_report for stamped past Needed.
GET
/v1/list_box_neededQuery
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| budgetId | string | Yes | — | Budget to evaluate. |
| boxId | string | No | — | Limit to one expense box. |
| asOfDate | string | No | today (UTC) | Calendar day yyyy-MM-dd for the projection. |
Response shape: { items }. Amounts are in box currency.
Response data
| Field | Type | Description |
|---|---|---|
| items | array | Box Needed rows. |
Item fields
| Field | Type | Description |
|---|---|---|
| boxId | string | Expense box id. |
| boxName | string | Expense box name. |
| currency | string | Box currency. |
| asOfDate | string | Projection day yyyy-MM-dd. |
| status | string | ready, undatedExpenses, missingCreditCycleEndDay, or noPlannedExpenses. |
| expectedInAccountToday | number | Opening Needed when status is ready. |
| expectedAfterTodaysBills | number | Closing Needed when status is ready. |
| hasOutflowsToday | boolean | True when planned outflows fall on asOfDate. |