#Forecast API

Forecasting answers the question monetr exists to answer: given what I've committed to and when I get paid, what does the next few months look like? It walks forward day by day, firing your funding schedules and your spending due dates in order, and reports the balance at each step.

Nothing here writes anything. All four endpoints are pure calculation, including the two that are POSTs. They're POSTs because they take a body describing a hypothetical, not because they change anything.

Forecasting can be slow on an account with a lot of spending objects, so the handlers have their own timeouts. Exceed them and you get a 408 rather than a hung request.

#GET Get a forecast

Projects the account's balance forward from now, returning an event for each day something happens. This is what draws the timeline charts in the app.

In the app: The timeline charts on the funding and goals pages.

GET /api/bank_accounts/:bankAccountId/forecast

Auth: API key, subscription required.

#Path parameters

#Query parameters

#Example

This account has two envelopes: a Coffee expense with 1315 in it, due on the 1st, and a New Laptop goal with 45000 in it. One funding schedule pays every other Friday, next on August 30th.

curl --request GET \
  --url "https://my.monetr.local/api/bank_accounts/bac_01gds6eqsq7h5mgevwtmw3cyxb/forecast?end=2024-09-02T05%3A00%3A00Z" \
  --user "$MONETR_API_KEY_ID:$MONETR_API_KEY_SECRET"

{
  "startingTime": "2024-08-28T14:03:11.882Z",
  "endingTime": "2024-09-02T05:00:00Z",
  "startingBalance": 46315,
  "endingBalance": 59642,
  "events": [
    {
      "date": "2024-08-30T05:00:00Z",
      "delta": 21327,
      "contribution": 21327,
      "transaction": 0,
      "balance": 67642,
      "spending": [
        {
          "date": "2024-08-30T05:00:00Z",
          "transactionAmount": 0,
          "contributionAmount": 6685,
          "rollingAllocation": 8000,
          "funding": [
            {
              "date": "2024-08-30T05:00:00Z",
              "originalDate": "2024-08-30T05:00:00Z",
              "weekendAvoided": false,
              "fundingScheduleId": "fund_01fpwx4xhvr8gs2fpsafd7nvpz"
            }
          ],
          "spendingId": "spnd_01fpwx67z8djhb8bqcy17mrzfe"
        },
        {
          "date": "2024-08-30T05:00:00Z",
          "transactionAmount": 0,
          "contributionAmount": 14642,
          "rollingAllocation": 59642,
          "funding": [
            {
              "date": "2024-08-30T05:00:00Z",
              "originalDate": "2024-08-30T05:00:00Z",
              "weekendAvoided": false,
              "fundingScheduleId": "fund_01fpwx4xhvr8gs2fpsafd7nvpz"
            }
          ],
          "spendingId": "spnd_01j3d7k2vwqrx8m5t9pnbeh4cz"
        }
      ],
      "funding": [
        {
          "date": "2024-08-30T05:00:00Z",
          "originalDate": "2024-08-30T05:00:00Z",
          "weekendAvoided": false,
          "fundingScheduleId": "fund_01fpwx4xhvr8gs2fpsafd7nvpz"
        }
      ]
    },
    {
      "date": "2024-09-01T05:00:00Z",
      "delta": -8000,
      "contribution": 0,
      "transaction": 8000,
      "balance": 59642,
      "spending": [
        {
          "date": "2024-09-01T05:00:00Z",
          "transactionAmount": 8000,
          "contributionAmount": 0,
          "rollingAllocation": 0,
          "funding": [],
          "spendingId": "spnd_01fpwx67z8djhb8bqcy17mrzfe"
        }
      ],
      "funding": []
    }
  ]
}

Two events: payday, where both envelopes get filled, and the 1st, where the Coffee envelope empties because that's when it comes due. The goal doesn't appear in the second event because nothing happened to it that day.

#Response attributes

Each event:

Each funding event:

Each spending event:

#Errors

#QUERY Estimate the cost of a new spending object

Answers "if I added this expense, what would it cost me per paycheck?" without creating anything. Use it to show someone the damage before they commit.

In the app: Nothing in the app uses this today. The new expense and goal forms work out their estimate another way.

QUERY /api/bank_accounts/:bankAccountId/forecast/spending
POST /api/bank_accounts/:bankAccountId/forecast/spending

Auth: API key, subscription required.

#Path parameters

#Body

The rule field is called recurrenceRule here, not ruleset like it is everywhere else on spending. Same format, different key. It's an inconsistency in the API, not a typo in these docs.

This endpoint doesn't run the shared validation, so mistakes come back as plain messages rather than a problems tree.

#Example

curl --request QUERY \
  --url "https://my.monetr.local/api/bank_accounts/bac_01gds6eqsq7h5mgevwtmw3cyxb/forecast/spending" \
  --user "$MONETR_API_KEY_ID:$MONETR_API_KEY_SECRET" \
  --header "Content-Type: application/json" \
  --data '{
    "fundingScheduleId": "fund_01fpwx4xhvr8gs2fpsafd7nvpz",
    "spendingType": "expense",
    "targetAmount": 8000,
    "currentAmount": 0,
    "nextRecurrence": "2024-09-01T05:00:00Z",
    "recurrenceRule": "DTSTART:20240901T050000Z\nRRULE:FREQ=MONTHLY;BYMONTHDAY=1"
  }'

{
  "estimatedCost": 4000
}

estimatedCost is how much a single funding event would need to put aside, in the currency's smallest unit. Here that's $40.00 per paycheck to cover an$80 monthly expense, which checks out: this schedule pays every other Friday, so roughly two paychecks cover each month.

Despite what the underlying function is called, this is the most common per-event contribution over the next two years, not the mean. Contributions vary from period to period, and the mode is the number you would actually quote someone, where an average would land between two amounts that never occur.

#Errors

#QUERY Estimate the next contribution

Answers "how much of my next paycheck is already spoken for?" It adds up what every spending object on one funding schedule will take at its next funding event.

In the app: The committed amount shown next to each funding schedule in the funding list.

QUERY /api/bank_accounts/:bankAccountId/forecast/next_funding
POST /api/bank_accounts/:bankAccountId/forecast/next_funding

Auth: API key, subscription required.

#Path parameters

#Body

#Example

curl --request QUERY \
  --url "https://my.monetr.local/api/bank_accounts/bac_01gds6eqsq7h5mgevwtmw3cyxb/forecast/next_funding" \
  --user "$MONETR_API_KEY_ID:$MONETR_API_KEY_SECRET" \
  --header "Content-Type: application/json" \
  --data '{
    "fundingScheduleId": "fund_01fpwx4xhvr8gs2fpsafd7nvpz"
  }'

{
  "nextContribution": 21327
}

Compare that against the schedule's estimatedDeposit from Get a funding schedule to work out what's left over.

#Errors

#QUERY Estimate the starting amount for a recurring expense

Answers "if I'd been budgeting for this all along, how much would already be set aside for it today?" Give it a recurring transaction and the funding schedule that would pay for it, and it works out what an expense for that charge would have in it right now. Use the result as the currentAmount when you create the expense, so it starts out where it would be instead of at zero.

In the app: Nothing in the app uses this yet.

QUERY /api/bank_accounts/:bankAccountId/forecast/initial

Auth: API key, subscription required.

#Path parameters

#Body

The expense it imagines uses the recurring transaction's ruleset for its due dates and its lastAmount as the target. It starts from the last time that charge was due, then adds up what the funding schedule would have put in since then, the same way a real expense gets funded. Whatever's in there today is the answer.

If the funding schedule is newer than that last charge, it gets treated like it has always existed, with its paydays carried back on the same days. So a funding schedule you set up yesterday still gives you a real number.

#Example

This account has an $8 GitHub charge on the 15th of every month, and gets paid every other Friday. The request was made on October 26th, 2026.

curl --request QUERY \
  --url "https://my.monetr.local/api/bank_accounts/bac_01gds6eqsq7h5mgevwtmw3cyxb/forecast/initial" \
  --user "$MONETR_API_KEY_ID:$MONETR_API_KEY_SECRET" \
  --header "Content-Type: application/json" \
  --data '{
    "transactionRecurringId": "txrc_01j6b4n8w2kq5t9r3xm7vdc6ph",
    "fundingScheduleId": "fund_01fpwx4xhvr8gs2fpsafd7nvpz"
  }'

{
  "currentAmount": 266
}

There's been one payday since the charge on the 15th, October 16th, and there are three paydays before the next charge on November 15th. So each one puts aside a third of the $8, and today there's$2.66 set aside.

#Response attributes

#Errors