On this page

get_financial_overview

What it answers

Read Executive Dashboard values from manually keyed imported Data Inputs, read-only Target Inputs, definitions, trailing averages and dashboard import freshness. Optional inclusive YYYY-MM range; defaults to the latest twelve available months. No person-level data. This is the Executive Dashboard imported snapshot, including frozen capacity/hours and read-only Target Inputs J/K monthly targets, and follows the template ratio of three-month averages; follow its inline report definitions. 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`	—
`range`	object	no	—	—
`range.from`	string	yes	—	pattern `^\d{4}-(?:0[1-9]\|1[0-2])$`
`range.to`	string	yes	—	pattern `^\d{4}-(?:0[1-9]\|1[0-2])$`

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.availableMonths: array of string
- data.availableRange: object
  - data.availableRange.first: string (pattern ^\d{4}-(?:0[1-9]|1[0-2])$)
  - data.availableRange.last: string (pattern ^\d{4}-(?:0[1-9]|1[0-2])$)
- data.selectedRange: object or null
  - data.selectedRange.first: string (pattern ^\d{4}-(?:0[1-9]|1[0-2])$)
  - data.selectedRange.last: string (pattern ^\d{4}-(?:0[1-9]|1[0-2])$)
- data.months: array of object
  - data.months[].month: string (pattern ^\d{4}-(?:0[1-9]|1[0-2])$)
  - data.months[].leadershipDashboard: object
    - data.months[].leadershipDashboard.financial: object or null
      - data.months[].leadershipDashboard.financial.income: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.months[].leadershipDashboard.financial.agi: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.months[].leadershipDashboard.financial.deliveryExpenses: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.months[].leadershipDashboard.financial.salesMarketingExpenses: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.months[].leadershipDashboard.financial.adminExpenses: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.months[].leadershipDashboard.financial.facilitiesExpenses: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.months[].leadershipDashboard.financial.month: string (pattern ^\d{4}-(?:0[1-9]|1[0-2])$)
    - data.months[].leadershipDashboard.utilization: object or null
      - data.months[].leadershipDashboard.utilization.grossCapacity: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.months[].leadershipDashboard.utilization.deliveryCapacity: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.months[].leadershipDashboard.utilization.deliveryHours: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.months[].leadershipDashboard.utilization.month: string (pattern ^\d{4}-(?:0[1-9]|1[0-2])$)
    - data.months[].leadershipDashboard.calculations: object or null
      - data.months[].leadershipDashboard.calculations.incomeShare: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.months[].leadershipDashboard.calculations.deliveryExpenseShare: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.months[].leadershipDashboard.calculations.salesMarketingExpenseShare: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.months[].leadershipDashboard.calculations.adminExpenseShare: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.months[].leadershipDashboard.calculations.facilitiesExpenseShare: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.months[].leadershipDashboard.calculations.deliveryIncome: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.months[].leadershipDashboard.calculations.deliveryMargin: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.months[].leadershipDashboard.calculations.operatingIncome: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.months[].leadershipDashboard.calculations.operatingMargin: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.months[].leadershipDashboard.calculations.abr: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.months[].leadershipDashboard.calculations.utilization: string or null (pattern ^-?\d+(?:\.\d+)?$)
    - data.months[].leadershipDashboard.comparisons: object
      - data.months[].leadershipDashboard.comparisons.income: object
        
        data.months[].leadershipDashboard.comparisons.income.actual: string or null (pattern ^-?\d+(?:\.\d+)?$)
        
        data.months[].leadershipDashboard.comparisons.income.target: string or null (pattern ^-?\d+(?:\.\d+)?$)
        
        data.months[].leadershipDashboard.comparisons.income.delta: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.months[].leadershipDashboard.comparisons.agi: same shape as data.months[].leadershipDashboard.comparisons.income
      - data.months[].leadershipDashboard.comparisons.abr: same shape as data.months[].leadershipDashboard.comparisons.income
      - data.months[].leadershipDashboard.comparisons.utilization: same shape as data.months[].leadershipDashboard.comparisons.income
      - data.months[].leadershipDashboard.comparisons.deliveryMargin: same shape as data.months[].leadershipDashboard.comparisons.income
      - data.months[].leadershipDashboard.comparisons.operatingMargin: same shape as data.months[].leadershipDashboard.comparisons.income
  - data.months[].missing: array of object
    - data.months[].missing[].code: string ("MISSING_INPUT", "UNDEFINED_RATIO", "MISSING_TARGET")
    - data.months[].missing[].message: string
    - data.months[].missing[].fields: array of string
- data.trailing: object
  - data.trailing.leadershipDashboard: object
    - data.trailing.leadershipDashboard.definition: string
    - data.trailing.leadershipDashboard.trailingAverages: object
      - data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare: object
        
        data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare.months: array of string
        
        data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare.value: string or null (pattern ^-?\d+(?:\.\d+)?$)
      - data.trailing.leadershipDashboard.trailingAverages.salesMarketingExpenseShare: same shape as data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare
      - data.trailing.leadershipDashboard.trailingAverages.adminExpenseShare: same shape as data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare
      - data.trailing.leadershipDashboard.trailingAverages.facilitiesExpenseShare: same shape as data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare
      - data.trailing.leadershipDashboard.trailingAverages.operatingMargin: same shape as data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare
      - data.trailing.leadershipDashboard.trailingAverages.deliveryMargin: same shape as data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare
      - data.trailing.leadershipDashboard.trailingAverages.abr: same shape as data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare
      - data.trailing.leadershipDashboard.trailingAverages.utilization: same shape as data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare
      - data.trailing.leadershipDashboard.trailingAverages.agi: same shape as data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare
    - data.trailing.leadershipDashboard.targetAverages: object
      - data.trailing.leadershipDashboard.targetAverages.income: same shape as data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare
      - data.trailing.leadershipDashboard.targetAverages.agi: same shape as data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare
      - data.trailing.leadershipDashboard.targetAverages.abr: same shape as data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare
      - data.trailing.leadershipDashboard.targetAverages.utilization: same shape as data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare
- data.monthlyTargets: array of object
  - data.monthlyTargets[].income: string or null (pattern ^-?\d+(?:\.\d+)?$)
  - data.monthlyTargets[].agi: string or null (pattern ^-?\d+(?:\.\d+)?$)
  - data.monthlyTargets[].abr: string or null (pattern ^-?\d+(?:\.\d+)?$)
  - data.monthlyTargets[].utilization: string or null (pattern ^-?\d+(?:\.\d+)?$)
  - data.monthlyTargets[].deliveryMargin: string or null (pattern ^-?\d+(?:\.\d+)?$)
  - data.monthlyTargets[].operatingMargin: string or null (pattern ^-?\d+(?:\.\d+)?$)
  - data.monthlyTargets[].month: string (pattern ^\d{4}-(?:0[1-9]|1[0-2])$)
- data.freshness: array of object
  - data.freshness[].source: string ("time-entries", "role-task-mappings", "annual-days", "dashboard-inputs")
  - data.freshness[].everCompleted: boolean
  - data.freshness[].completedAt: string (date-time) or null
- data.definitions: map of string to string, optional
  - data.definitions.*: string
- data.caveats: array of object
  - data.caveats[].code: string
  - data.caveats[].message: 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_financial_overview",
  "arguments": {}
}

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

Questions and answers

What does get_financial_overview answer?

Which arguments does get_financial_overview accept?

Argument Type Required Default Allowed values account string (uuid) no — — includeDefinitions boolean no true — range object no — — range.from string yes — pattern ^\d{4}-(?:0[1-9]|1[0-2])$ range.to string yes — pattern ^\d{4}-(?:0[1-9]|1[0-2])$

What does get_financial_overview return?

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