Kubecost Allocation API

naftiko: 1.0.0-alpha2
info:
  label: Kubecost Allocation API
  description: The Allocation API retrieves cost allocation information for any Kubernetes concept, such as cost by namespace,
    label, deployment, service, and more. It is directly integrated with the Kubecost ETL caching layer and CSV pipeline so
    it can scale for large clusters.
  tags:
  - Kubecost
  - API
  created: '2026-05-06'
  modified: '2026-05-06'
capability:
  consumes:
  - type: http
    namespace: kubecost
    baseUri: http://localhost:9090
    description: Kubecost Allocation API HTTP API.
    resources:
    - name: model-allocation
      path: /model/allocation
      operations:
      - name: getallocation
        method: GET
        description: Kubecost Query allocation cost data
        inputParameters:
        - name: window
          in: query
          type: string
          required: true
          description: Duration of time over which to query. Accepts units of time (e.g. 3d, 24h, 7d), relative time (e.g.
            yesterday, lastweek, lastmonth), or RFC3339 date pairs.
        - name: aggregate
          in: query
          type: string
          description: 'Field by which to aggregate results. Supported values include cluster, namespace, controllerKind,
            controller, service, deployment, statefulset, daemonset, job, '
        - name: step
          in: query
          type: string
          description: Duration of a single allocation set. If unspecified, this defaults to the window, so that you receive
            exactly one set for the entire window.
        - name: accumulate
          in: query
          type: boolean
          description: If true, sum the entire range of sets into a single set.
        - name: idle
          in: query
          type: boolean
          description: Whether to return idle cost. If true, idle allocations are returned.
        - name: external
          in: query
          type: boolean
          description: Whether to include external (out-of-cluster) costs.
        - name: filterClusters
          in: query
          type: string
          description: Filter results by cluster name (comma-separated).
        - name: filterNamespaces
          in: query
          type: string
          description: Filter results by namespace (comma-separated).
        - name: filterControllerKinds
          in: query
          type: string
          description: Filter results by controller kind (comma-separated).
        - name: filterControllers
          in: query
          type: string
          description: Filter results by controller name (comma-separated).
        - name: filterLabels
          in: query
          type: string
          description: Filter results by label in the format label:value (comma-separated).
        - name: filterAnnotations
          in: query
          type: string
          description: Filter results by annotation in the format annotation:value (comma-separated).
        - name: filterServices
          in: query
          type: string
          description: Filter results by service (comma-separated).
        - name: shareIdle
          in: query
          type: boolean
          description: If true, idle cost is allocated proportionally across tenants.
        - name: splitIdle
          in: query
          type: boolean
          description: If true, idle cost is split into separate allocations by cluster and node.
        - name: idleByNode
          in: query
          type: boolean
          description: If true, idle allocations are created on a per-node basis.
        - name: format
          in: query
          type: string
          description: Output format. Supports csv and json.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: model-allocation-totals
      path: /model/allocation/totals
      operations:
      - name: getallocationtotals
        method: GET
        description: Kubecost Query total allocation costs
        inputParameters:
        - name: window
          in: query
          type: string
          required: true
          description: Duration of time over which to query.
        - name: aggregate
          in: query
          type: string
          description: Field by which to aggregate results.
        - name: filterClusters
          in: query
          type: string
        - name: filterNamespaces
          in: query
          type: string
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: kubecost-rest
    description: REST adapter for Kubecost Allocation API.
    resources:
    - path: /model/allocation
      name: getallocation
      operations:
      - method: GET
        name: getallocation
        description: Kubecost Query allocation cost data
        call: kubecost.getallocation
        outputParameters:
        - type: object
          mapping: $.
    - path: /model/allocation/totals
      name: getallocationtotals
      operations:
      - method: GET
        name: getallocationtotals
        description: Kubecost Query total allocation costs
        call: kubecost.getallocationtotals
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: kubecost-mcp
    transport: http
    description: MCP adapter for Kubecost Allocation API for AI agent use.
    tools:
    - name: getallocation
      description: Kubecost Query allocation cost data
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: kubecost.getallocation
      with:
        window: tools.window
        aggregate: tools.aggregate
        step: tools.step
        accumulate: tools.accumulate
        idle: tools.idle
        external: tools.external
        filterClusters: tools.filterClusters
        filterNamespaces: tools.filterNamespaces
        filterControllerKinds: tools.filterControllerKinds
        filterControllers: tools.filterControllers
        filterLabels: tools.filterLabels
        filterAnnotations: tools.filterAnnotations
        filterServices: tools.filterServices
        shareIdle: tools.shareIdle
        splitIdle: tools.splitIdle
        idleByNode: tools.idleByNode
        format: tools.format
      inputParameters:
      - name: window
        type: string
        description: Duration of time over which to query. Accepts units of time (e.g. 3d, 24h, 7d), relative time (e.g. yesterday,
          lastweek, lastmonth), or RFC3339 date pairs.
        required: true
      - name: aggregate
        type: string
        description: 'Field by which to aggregate results. Supported values include cluster, namespace, controllerKind, controller,
          service, deployment, statefulset, daemonset, job, '
      - name: step
        type: string
        description: Duration of a single allocation set. If unspecified, this defaults to the window, so that you receive
          exactly one set for the entire window.
      - name: accumulate
        type: boolean
        description: If true, sum the entire range of sets into a single set.
      - name: idle
        type: boolean
        description: Whether to return idle cost. If true, idle allocations are returned.
      - name: external
        type: boolean
        description: Whether to include external (out-of-cluster) costs.
      - name: filterClusters
        type: string
        description: Filter results by cluster name (comma-separated).
      - name: filterNamespaces
        type: string
        description: Filter results by namespace (comma-separated).
      - name: filterControllerKinds
        type: string
        description: Filter results by controller kind (comma-separated).
      - name: filterControllers
        type: string
        description: Filter results by controller name (comma-separated).
      - name: filterLabels
        type: string
        description: Filter results by label in the format label:value (comma-separated).
      - name: filterAnnotations
        type: string
        description: Filter results by annotation in the format annotation:value (comma-separated).
      - name: filterServices
        type: string
        description: Filter results by service (comma-separated).
      - name: shareIdle
        type: boolean
        description: If true, idle cost is allocated proportionally across tenants.
      - name: splitIdle
        type: boolean
        description: If true, idle cost is split into separate allocations by cluster and node.
      - name: idleByNode
        type: boolean
        description: If true, idle allocations are created on a per-node basis.
      - name: format
        type: string
        description: Output format. Supports csv and json.
      outputParameters:
      - type: object
        mapping: $.
    - name: getallocationtotals
      description: Kubecost Query total allocation costs
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: kubecost.getallocationtotals
      with:
        window: tools.window
        aggregate: tools.aggregate
        filterClusters: tools.filterClusters
        filterNamespaces: tools.filterNamespaces
      inputParameters:
      - name: window
        type: string
        description: Duration of time over which to query.
        required: true
      - name: aggregate
        type: string
        description: Field by which to aggregate results.
      - name: filterClusters
        type: string
        description: filterClusters
      - name: filterNamespaces
        type: string
        description: filterNamespaces
      outputParameters:
      - type: object
        mapping: $.