# get_scenario

## What it answers

Open one scenario from list_scenarios: its stored window, Include pending setting and model-input overrides, and the figures the Model Calculator shows for it (inputs, outputs, shares), calculated by the same pipeline over the scenario's own window with its saved Included rows. scenarioId "base" is the read-only Base case and needs range. missingRows lists saved choices that no longer match the current payroll; names and dates require People grid view, otherwise the list is empty with a rows-withheld caveat. includeRows adds the payroll rows with the rowKey that save_scenario accepts; names identify people, so it needs People grid view and otherwise returns a rows-withheld caveat. Requires administrator or Model Calculator access. Read only. Read parakeeto://methodology for shared response conventions and INVALID_ARGUMENT guidance.

Read-only.

## Arguments

| Argument | Type | Required | Default | Allowed values |
| --- | --- | --- | --- | --- |
| `account` | string (uuid) | no | — | — |
| `includeDefinitions` | boolean | no | `true` | — |
| `scenarioId` | string | yes | — | `minLength: 1`; `maxLength: 64` |
| `range` | object | no | — | — |
| `range.from` | string | yes | — | pattern `^\d{4}-\d{2}-\d{2}$` |
| `range.to` | string | yes | — | pattern `^\d{4}-\d{2}-\d{2}$` |
| `payrollGridId` | string (uuid) | no | — | — |
| `expenseGridId` | string (uuid) | no | — | — |
| `includeRows` | boolean | no | `false` | — |

## Returned fields

The result is an envelope: `ok: true` with `data`, or `ok: false` with `error`. Error codes: `MODEL_CALCULATOR_ACCESS_REQUIRED`, `PAYROLL_GRID_MISSING`, `PAYROLL_GRID_REQUIRED`, `PROJECT_GRID_REQUIRED`, `EXPENSE_GRID_REQUIRED`, `PAYROLL_ENTRY_REFERENCE_STALE`, `ACCOUNT_NOT_FOUND`, `ACCOUNT_CONFIGURATION_MISSING`, `NO_IMPORTED_TIME`, `NOTHING_IMPORTED`, `ACCOUNT_REQUIRED`, `NO_REACHABLE_ACCOUNTS`, `FEATURE_NOT_ENTITLED`, `PERMISSION_DENIED`, `CALCULATION_FAILED`, `INTERNAL_ERROR`, `INVALID_ARGUMENT`.

- `data`: object
  - `data.account`: string (uuid)
  - `data.scenario`: object
    - `data.scenario.id`: string
    - `data.scenario.name`: string
    - `data.scenario.readOnly`: boolean
    - `data.scenario.revision`: string or null (pattern `^[1-9]\d*$`)
    - `data.scenario.window`: object or null
      - `data.scenario.window.from`: string (pattern `^\d{4}-\d{2}-\d{2}$`)
      - `data.scenario.window.to`: string (pattern `^\d{4}-\d{2}-\d{2}$`)
    - `data.scenario.includePending`: boolean or null
    - `data.scenario.createdByName`: string or null
    - `data.scenario.updatedAt`: string (date-time) or null
    - `data.scenario.canManage`: boolean
  - `data.range`: object
    - `data.range.from`: string (pattern `^\d{4}-\d{2}-\d{2}$`)
    - `data.range.to`: string (pattern `^\d{4}-\d{2}-\d{2}$`)
  - `data.payrollGrid`: object
    - `data.payrollGrid.id`: string (uuid)
    - `data.payrollGrid.name`: string
  - `data.expenseGrid`: object or null
    - `data.expenseGrid.id`: string (uuid)
    - `data.expenseGrid.name`: string
  - `data.annualDays`: string (pattern `^-?\d+(?:\.\d+)?$`)
  - `data.gridFreshness`: array of object
    - `data.gridFreshness[].kind`: string (`"payroll"`, `"expense"`, `"project"`)
    - `data.gridFreshness[].gridId`: string (uuid)
    - `data.gridFreshness[].name`: string
    - `data.gridFreshness[].storage`: string (`"sheet"`, `"database"`)
    - `data.gridFreshness[].sheetRefreshedAt`: string (date-time) or null
  - `data.overrides`: object
    - `data.overrides.grossCapacity`: string, optional (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.overrides.modelAbr`: string, optional (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.overrides.modelUtilization`: string, optional (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.overrides.deliveryPayrollBudget`: string, optional (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.overrides.deliveryExpenseBudget`: string, optional (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.overrides.smPayrollBudget`: string, optional (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.overrides.smExpenseBudget`: string, optional (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.overrides.adminPayrollBudget`: string, optional (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.overrides.adminExpenseBudget`: string, optional (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.overrides.facilitiesExpenseBudget`: string, optional (pattern `^-?\d+(?:\.\d+)?$`)
  - `data.inputs`: object
    - `data.inputs.grossCapacity`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.inputs.modelAbr`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.inputs.modelUtilization`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.inputs.deliveryPayrollBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.inputs.deliveryExpenseBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.inputs.smPayrollBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.inputs.smExpenseBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.inputs.adminPayrollBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.inputs.adminExpenseBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.inputs.facilitiesExpenseBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
  - `data.outputs`: object
    - `data.outputs.agencyGrossIncome`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.outputs.modelDeliveryBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.outputs.modelSmBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.outputs.modelAdminBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.outputs.modelFacilitiesBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.outputs.modelOperatingIncome`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
  - `data.shares`: object
    - `data.shares.modelDeliveryBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.shares.modelSmBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.shares.modelAdminBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.shares.modelFacilitiesBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.shares.modelOperatingIncome`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
  - `data.caveats`: array of object
    - `data.caveats[].code`: string
    - `data.caveats[].message`: string
    - `data.caveats[].reference`: string, optional
  - `data.missingRows`: array of object
    - `data.missingRows[].name`: string
    - `data.missingRows[].startDate`: string or null
  - `data.rows`: array of object, optional
    - `data.rows[].rowKey`: object
      - `data.rows[].rowKey.name`: string (`maxLength: 500`)
      - `data.rows[].rowKey.startDate`: string or null (`maxLength: 10`)
      - `data.rows[].rowKey.occurrence`: string (pattern `^\d{1,6}$`)
      - `data.rows[].rowKey.siblings`: string (pattern `^[1-9]\d{0,5}$`)
      - `data.rows[].rowKey.hint`: string or null (`maxLength: 100`)
    - `data.rows[].name`: string
    - `data.rows[].startDate`: string or null
    - `data.rows[].endDate`: string or null
    - `data.rows[].included`: boolean
    - `data.rows[].choice`: boolean or null
    - `data.rows[].effective`: boolean
  - `data.definitions`: map of string to string, optional
    - `data.definitions.*`: string

On failure:

- `error`: object
  - `error.code`: string (`"MODEL_CALCULATOR_ACCESS_REQUIRED"`, `"PAYROLL_GRID_MISSING"`, `"PAYROLL_GRID_REQUIRED"`, `"PROJECT_GRID_REQUIRED"`, `"EXPENSE_GRID_REQUIRED"`, `"PAYROLL_ENTRY_REFERENCE_STALE"`, `"ACCOUNT_NOT_FOUND"`, `"ACCOUNT_CONFIGURATION_MISSING"`, `"NO_IMPORTED_TIME"`, `"NOTHING_IMPORTED"`, `"ACCOUNT_REQUIRED"`, `"NO_REACHABLE_ACCOUNTS"`, `"FEATURE_NOT_ENTITLED"`, `"PERMISSION_DENIED"`, `"CALCULATION_FAILED"`, `"INTERNAL_ERROR"`, `"INVALID_ARGUMENT"`)
  - `error.argument`: string, optional (`minLength: 1`)
  - `error.message`: string
  - `error.accounts`: array of object, optional
    - `error.accounts[].id`: string (uuid)
    - `error.accounts[].name`: string
  - `error.payrollGrids`: array of object, optional
    - `error.payrollGrids[]`: same shape as `error.accounts[]`
  - `error.projectGrids`: array of object, optional
    - `error.projectGrids[]`: same shape as `error.accounts[]`
  - `error.expenseGrids`: array of object, optional
    - `error.expenseGrids[]`: same shape as `error.accounts[]`
  - `error.context`: object, optional
    - `error.context.account`: object
      - Further fields: see the response.
    - `error.context.imports`: array of object
      - Further fields: see the response.
    - `error.context.hasTimeEntries`: boolean
    - `error.context.reports`: array of object
      - Further fields: see the response.

## Definitions

Returned in `definitions` when `includeDefinitions` is true (the default). It is a map of string to string: each key names a field and each value is its definition text.

## Caveats

Codes are not enumerated in the schema; read each `code` and `message`.

Read every caveat before interpreting a figure. See [methodology](</methodology.md>) on how to communicate caveats and data-quality conditions.

## Example call

```json
{
  "name": "get_scenario",
  "arguments": {
    "scenarioId": "base",
    "range": {
      "from": "2026-10-05",
      "to": "2026-10-09"
    }
  }
}
```

Add `account` with an identifier from `list_accounts`; omit it only when the connection reaches exactly one account.