GET /api/agent/forecast
Returns the latest ForecastSnapshot for the given scenario. Omit scenarioId to use the org's default BASE scenario.
Auth
- Required scope:
READ_FORECAST - Header:
Authorization: Bearer cr_live_<prefix>_<secret>
Query parameters
| Name | Type | Required | Notes |
|---|---|---|---|
scenarioId | string | no | Optional scenario id. Defaults to the org's default BASE scenario. |
Responses
200 — Serialised 13-week forecast
Body: ForecastResponse
| Field | Type | Required | Notes |
|---|---|---|---|
scenarioId | string | yes | |
scenarioName | string | no | |
scenarioKind | string · one of BASE BEST WORST CUSTOM | no | |
computedAt | string (date-time) | yes | |
weeks | array of ForecastWeek | yes | |
startingCash | string | yes | |
endingCash | string | yes | |
minClosingCash | string | no | |
minClosingCashWeekIndex | integer | no | |
totalInflow | string | no | |
totalOutflow | string | no | |
redactedItemCount | integer | yes | Sum across all weeks of (week, account) pairs whose account name was rewritten to "Sensitive account" inside weeks[].categories.accounts[id].name for this caller. Always 0 when the key carries READ_SENSITIVE. The net cash trajectory (opening/inflow/outflow/closing) is never masked: a sensitive account's totals still feed weekly amounts (Stripe restricted-key pattern). |
notesForAgent | array of AgentNote | no | |
billingAlert | BillingAlert | no | |
xeroAlert | XeroAlert | no |
401 — Unauthorized
Body: ErrorResponse
| Field | Type | Required | Notes |
|---|---|---|---|
error | string | yes |
404 — Scenario doesn't belong to the org, or no snapshot exists yet
Body: ErrorResponse
| Field | Type | Required | Notes |
|---|---|---|---|
error | string | yes |
Response headers
Every successful response carries X-CashRunway-Subscription, X-CashRunway-Plan, X-CashRunway-Quota-Remaining, and X-CashRunway-Quota-Reset. Trialing subscriptions also include X-CashRunway-Trial-Days-Remaining. See the overview for details.