ParakeetoDocumentation
On this page

get_utilization_by_tenure

What it answers

Get named hours, capacity and utilization per Tenure band and per person, by month or Monday-start week and for the whole window. Optional unit is months (default) or weeks. Required real YYYY-MM-DD range.from/range.to dates select inclusive containing periods. periods holds overall and per-band figures for each period; window adds one row per person (at most 500 with explicit truncation). Tenure band is under-1-year, 1-to-3-years, 3-years-or-more or unknown, measured from the person's earliest included payroll start date; the start date itself is never returned. Utilization is summed delivery hours divided by summed gross capacity. No compensation. Read definitions, caveats and truncation before interpreting figures. Decimal strings preserve served numeric figures. 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 yes — —
range.from string yes — pattern ^\d{4}-\d{2}-\d{2}$
range.to string yes — pattern ^\d{4}-\d{2}-\d{2}$
unit string no "months" "months", "weeks"

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.unit: string ("months", "weeks")
    • data.from: string (pattern ^\d{4}-\d{2}-\d{2}$)
    • data.to: string (pattern ^\d{4}-\d{2}-\d{2}$)
    • data.window: object
      • data.window.overall: object
        • data.window.overall.grossCapacity: string (pattern ^-?\d+(?:\.\d+)?$)
        • data.window.overall.deliveryCapacity: string (pattern ^-?\d+(?:\.\d+)?$)
        • data.window.overall.deliveryHours: string (pattern ^-?\d+(?:\.\d+)?$)
        • data.window.overall.utilization: string (pattern ^-?\d+(?:\.\d+)?$)
      • data.window.tenureBands: array of object
        • data.window.tenureBands[].grossCapacity: string (pattern ^-?\d+(?:\.\d+)?$)
        • data.window.tenureBands[].deliveryCapacity: string (pattern ^-?\d+(?:\.\d+)?$)
        • data.window.tenureBands[].deliveryHours: string (pattern ^-?\d+(?:\.\d+)?$)
        • data.window.tenureBands[].utilization: string (pattern ^-?\d+(?:\.\d+)?$)
        • data.window.tenureBands[].tenureBand: string ("under-1-year", "1-to-3-years", "3-years-or-more", "unknown")
      • data.window.people: array of object
        • data.window.people[].grossCapacity: string (pattern ^-?\d+(?:\.\d+)?$)
        • data.window.people[].deliveryCapacity: string (pattern ^-?\d+(?:\.\d+)?$)
        • data.window.people[].deliveryHours: string (pattern ^-?\d+(?:\.\d+)?$)
        • data.window.people[].utilization: string (pattern ^-?\d+(?:\.\d+)?$)
        • data.window.people[].tenureBand: string ("under-1-year", "1-to-3-years", "3-years-or-more", "unknown")
        • data.window.people[].employeeName: string
    • data.periods: array of object
      • data.periods[].periodStart: string (pattern ^\d{4}-\d{2}-\d{2}$)
      • data.periods[].overall: same shape as data.window.overall
      • data.periods[].tenureBands: array of object
        • data.periods[].tenureBands[]: same shape as data.window.tenureBands[]
    • data.truncation: object
      • data.truncation.limit: number (500)
      • data.truncation.totalRows: integer (minimum: 0)
      • data.truncation.returnedRows: integer (minimum: 0)
      • data.truncation.omittedRows: integer (minimum: 0)
      • data.truncation.message: string or null
    • data.annualDays: string (pattern ^-?\d+(?:\.\d+)?$)
    • 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.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.definitions: map of string to string, optional
      • data.definitions.*: string
    • data.caveats: array of object
      • One of:
        • Variant 1 (code is "omission"):
          • data.caveats[].code: string ("omission")
          • data.caveats[].source: string ("payroll", "time")
          • data.caveats[].employeeName: string, optional
          • data.caveats[].rowPosition: integer (exclusiveMinimum: 0)
          • data.caveats[].message: string
        • Variant 2 (code is "allocation-mismatch"):
          • data.caveats[].code: string ("allocation-mismatch")
          • data.caveats[].employeeName: string
          • data.caveats[].startDate: string or null (pattern ^\d{4}-\d{2}-\d{2}$)
          • data.caveats[].weeklyHours: string (pattern ^-?\d+(?:\.\d+)?$)
          • data.caveats[].targetHoursSum: string (pattern ^-?\d+(?:\.\d+)?$)
          • data.caveats[].message: string
        • Variant 3 (code is "data-condition", id is "payroll-duplicate-start-date-double-count"):
          • data.caveats[].code: string ("data-condition")
          • data.caveats[].id: string ("payroll-duplicate-start-date-double-count")
          • data.caveats[].rowCount: integer (exclusiveMinimum: 0)
          • data.caveats[].employeeName: string
          • data.caveats[].startDate: string (pattern ^\d{4}-\d{2}-\d{2}$)
          • data.caveats[].roleCategories: array of string
          • data.caveats[].latestPeriod: string, optional (pattern ^\d{4}-\d{2}-\d{2}$)
          • data.caveats[].periods: array of object, optional
            • data.caveats[].periods[].date: string (pattern ^\d{4}-\d{2}-\d{2}$)
            • data.caveats[].periods[].roles: array of string
            • data.caveats[].periods[].rollingRoles: array of string
            • data.caveats[].periods[].overall: boolean
            • data.caveats[].periods[].rollingOverall: boolean
          • data.caveats[].teamRoles: array of string, optional
          • 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

  • omission. Also carries source, employeeName, rowPosition.
  • allocation-mismatch. Also carries employeeName, startDate, weeklyHours, targetHoursSum.
  • data-condition. Also carries id, rowCount, employeeName, startDate, roleCategories, latestPeriod, periods, teamRoles.

Read every caveat before interpreting a figure. See methodology on how to communicate caveats and data-quality conditions.

Example call

{
  "name": "get_utilization_by_tenure",
  "arguments": {
    "range": {
      "from": "2026-01-01",
      "to": "2026-12-31"
    }
  }
}

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

Questions and answers

What does get_utilization_by_tenure answer?

Get named hours, capacity and utilization per Tenure band and per person, by month or Monday-start week and for the whole window. Optional unit is months (default) or weeks. Required real YYYY-MM-DD range.from/range.to dates select inclusive containing periods. periods holds overall and per-band figures for each period; window adds one row per person (at most 500 with explicit truncation). Tenure band is under-1-year, 1-to-3-years, 3-years-or-more or unknown, measured from the person's earliest included payroll start date; the start date itself is never returned. Utilization is summed delivery hours divided by summed gross capacity. No compensation. Read definitions, caveats and truncation before interpreting figures. Decimal strings preserve served numeric figures. Read parakeeto://methodology for shared response conventions and INVALID_ARGUMENT guidance.

Which arguments does get_utilization_by_tenure accept?

Argument Type Required Default Allowed values account string (uuid) no — — includeDefinitions boolean no true — range object yes — — range.from string yes — pattern ^\d{4}-\d{2}-\d{2}$ range.to string yes — pattern ^\d{4}-\d{2}-\d{2}$ unit string no "months" "months", "weeks"

What does get_utilization_by_tenure return?

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

Read as Markdown