ParakeetoDocumentation
On this page

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 on how to communicate caveats and data-quality conditions.

Example call

{
  "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.

Questions and answers

What does get_scenario answer?

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.

Which arguments does get_scenario accept?

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 —

What does get_scenario return?

The result is an envelope: ok: true with data, or ok: false with error.

Read as Markdown