# budgets.scenarios.run

Test whether the company can afford founder or staff pay hourly (hours per week required), biweekly (every 14 days) or monthly for a chosen number of weeks or months. Uses the same dated cash-flow calculation as Budgets > Scenarios and the terminal, protects accrued tax reserves, includes recurring and one-off costs, employer burden, a cash buffer, an optional pay ramp, and explicit monthly revenue assumptions. Returns the proposal, no-pay baseline, smaller/delayed/ramp alternatives, first cash shortfall, affordable duration, maximum rate, earliest feasible start within a bounded search and required monthly revenue. Scenario-only cash and source overrides do not edit books; source IDs must come from budgets.scenarios.context. Missing data remains incomplete. Rerun this action for every follow-up comparison instead of inventing calculations. Does not create payroll, approve pay, pay tax or transfer funds.

`GET | POST /api/v1/accounting/budgets.scenarios.run`

Permissions: `accounting:read` · Roles: admin, finance

MCP tool: `accounting_budgets_scenarios_run`

## Fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `currency` | string | Yes | Three-letter currency code, such as CAD or USD. |
| `personName` | string |  | 1–160 characters. |
| `rate` | object | Yes | No other fields. |
| `rate.basis` | enum | Yes | One of: `hourly`, `biweekly`, `monthly`. |
| `rate.amountMinor` | string | Yes | An amount in cents (the currency's smallest unit), written as a whole-number string such as "1250" for $12.50. Matches ^\d{1,15}$. |
| `rate.hoursPerWeek` | number |  | 0.25 to 168. |
| `startsOn` | string (date) | Yes | A date, as YYYY-MM-DD. |
| `duration` | object | Yes | No other fields. |
| `duration.value` | integer | Yes | 1 to 104. |
| `duration.unit` | enum | Yes | One of: `weeks`, `months`. |
| `employerBurdenBps` | integer |  | 0 to 10000. |
| `minimumCashMinor` | string |  | An amount in cents (the currency's smallest unit), written as a whole-number string such as "1250" for $12.50. Matches ^\d{1,15}$. |
| `monthlyRevenueMinor` | string |  | An amount in cents (the currency's smallest unit), written as a whole-number string such as "1250" for $12.50. Matches ^\d{1,15}$. |
| `monthlyExpenseMinor` | string |  | An amount in cents (the currency's smallest unit), written as a whole-number string such as "1250" for $12.50. Matches ^\d{1,15}$. |
| `cashOverrideMinor` | string |  | An amount in cents (the currency's smallest unit), written as a whole-number string such as "1250" for $12.50. Matches ^\d{1,15}$. |
| `obligationOverrides` | array of objects |  | at most 100 items. |
| `obligationOverrides[].id` | string | Yes | The record's ID. 1–200 characters. |
| `obligationOverrides[].amountMinor` | string | Yes | An amount in cents (the currency's smallest unit), written as a whole-number string such as "1250" for $12.50. Matches ^\d{1,15}$. |
| `obligationOverrides[].date` | string (date) | Yes | A date, as YYYY-MM-DD. |
| `extraExpenses` | array of objects |  | at most 100 items. |
| `extraExpenses[].name` | string | Yes | A display name. 1–160 characters. |
| `extraExpenses[].date` | string (date) | Yes | A date, as YYYY-MM-DD. |
| `extraExpenses[].amountMinor` | string | Yes | An amount in cents (the currency's smallest unit), written as a whole-number string such as "1250" for $12.50. Matches ^\d{1,15}$. |
| `extraExpenses[].kind` | enum |  | Which kind of record or job this is. One of: `expense`, `tax`. |
| `ramp` | object |  | No other fields. |
| `ramp.after` | object | Yes | No other fields. |
| `ramp.after.value` | integer | Yes | 1 to 104. |
| `ramp.after.unit` | enum | Yes | One of: `weeks`, `months`. |
| `ramp.amountMinor` | string | Yes | An amount in cents (the currency's smallest unit), written as a whole-number string such as "1250" for $12.50. Matches ^\d{1,15}$. |

## Example request

```bash
curl https://app.getoatmilk.com/api/v1/accounting/budgets.scenarios.run \
  -H "Authorization: Bearer $OATMILK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "currency": "CAD",
  "rate": {
    "basis": "hourly",
    "amountMinor": "1250",
    "hoursPerWeek": 1
  },
  "startsOn": "2026-09-01",
  "duration": {
    "value": 1,
    "unit": "weeks"
  }
}'
```

Reference page: https://app.getoatmilk.com/docs/api/budgets.scenarios.run