FinOps Foundation FOCUS Cost and Usage API

naftiko: 1.0.0-alpha2
info:
  label: FinOps Foundation FOCUS Cost and Usage API
  description: An API modeled on the FinOps Open Cost and Usage Specification (FOCUS) v1.3, which defines a standard schema
    for cloud, SaaS, and other technology billing data. FOCUS normalizes billing datasets across providers to reduce complexity
    for FinOps practitioners. This specification models the Cost and Usage dataset and the Contract Commitment dataset defined
    by the FOCUS standard, enabling programmatic access to FOCUS-compliant billing data. The FOCUS specification is maintained
    by the FinOps Foundation under the Linux Foundation.
  tags:
  - Finops
  - Foundation
  - API
  created: '2026-05-06'
  modified: '2026-05-06'
capability:
  consumes:
  - type: http
    namespace: finops-foundation
    baseUri: https://api.example.com/focus/v1
    description: FinOps Foundation FOCUS Cost and Usage API HTTP API.
    authentication:
      type: bearer
      token: '{{FINOPS_FOUNDATION_TOKEN}}'
    resources:
    - name: cost-and-usage
      path: /cost-and-usage
      operations:
      - name: listcostandusage
        method: GET
        description: FinOps Foundation List cost and usage records
        inputParameters:
        - name: billingPeriodStart
          in: query
          type: string
          description: Filter by billing period start date (inclusive). Format is date-time per RFC 3339.
        - name: billingPeriodEnd
          in: query
          type: string
          description: Filter by billing period end date (exclusive). Format is date-time per RFC 3339.
        - name: chargeCategory
          in: query
          type: string
          description: Filter by charge category (e.g., Usage, Purchase, Tax, Credit, Adjustment).
        - name: providerName
          in: query
          type: string
          description: Filter by the name of the entity that made the resource or service available.
        - name: serviceName
          in: query
          type: string
          description: Filter by the display name of the service that was purchased.
        - name: serviceCategory
          in: query
          type: string
          description: Filter by the highest-level classification of a service (e.g., Compute, Storage, Networking, Database).
        - name: region
          in: query
          type: string
          description: Filter by the isolated geographic area where a resource is provisioned or a service is provided.
        - name: resourceId
          in: query
          type: string
          description: Filter by unique identifier assigned to a resource by the provider.
        - name: subAccountId
          in: query
          type: string
          description: Filter by the identifier for a sub account.
        - name: billingCurrency
          in: query
          type: string
          description: Filter by the currency that a charge was billed in.
        - name: pageSize
          in: query
          type: integer
          description: Number of records to return per page.
        - name: pageToken
          in: query
          type: string
          description: Token for retrieving the next page of results.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: cost-and-usage-export
      path: /cost-and-usage/export
      operations:
      - name: exportcostandusage
        method: POST
        description: FinOps Foundation Export cost and usage data
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: cost-and-usage-export-jobid
      path: /cost-and-usage/export/{jobId}
      operations:
      - name: getcostandusageexportstatus
        method: GET
        description: FinOps Foundation Get cost and usage export job status
        inputParameters:
        - name: jobId
          in: path
          type: string
          required: true
          description: The unique identifier for the export job.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: contract-commitments
      path: /contract-commitments
      operations:
      - name: listcontractcommitments
        method: GET
        description: FinOps Foundation List contract commitment records
        inputParameters:
        - name: commitmentDiscountId
          in: query
          type: string
          description: Filter by the identifier assigned to a commitment discount by the provider.
        - name: billingAccountId
          in: query
          type: string
          description: Filter by the unique identifier for a billing account.
        - name: pageSize
          in: query
          type: integer
          description: Number of records to return per page.
        - name: pageToken
          in: query
          type: string
          description: Token for retrieving the next page of results.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: schema
      path: /schema
      operations:
      - name: getschemametadata
        method: GET
        description: FinOps Foundation Get FOCUS schema metadata
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: finops-foundation-rest
    description: REST adapter for FinOps Foundation FOCUS Cost and Usage API.
    resources:
    - path: /cost-and-usage
      name: listcostandusage
      operations:
      - method: GET
        name: listcostandusage
        description: FinOps Foundation List cost and usage records
        call: finops-foundation.listcostandusage
        outputParameters:
        - type: object
          mapping: $.
    - path: /cost-and-usage/export
      name: exportcostandusage
      operations:
      - method: POST
        name: exportcostandusage
        description: FinOps Foundation Export cost and usage data
        call: finops-foundation.exportcostandusage
        outputParameters:
        - type: object
          mapping: $.
    - path: /cost-and-usage/export/{jobId}
      name: getcostandusageexportstatus
      operations:
      - method: GET
        name: getcostandusageexportstatus
        description: FinOps Foundation Get cost and usage export job status
        call: finops-foundation.getcostandusageexportstatus
        with:
          jobId: rest.jobId
        outputParameters:
        - type: object
          mapping: $.
    - path: /contract-commitments
      name: listcontractcommitments
      operations:
      - method: GET
        name: listcontractcommitments
        description: FinOps Foundation List contract commitment records
        call: finops-foundation.listcontractcommitments
        outputParameters:
        - type: object
          mapping: $.
    - path: /schema
      name: getschemametadata
      operations:
      - method: GET
        name: getschemametadata
        description: FinOps Foundation Get FOCUS schema metadata
        call: finops-foundation.getschemametadata
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: finops-foundation-mcp
    transport: http
    description: MCP adapter for FinOps Foundation FOCUS Cost and Usage API for AI agent use.
    tools:
    - name: listcostandusage
      description: FinOps Foundation List cost and usage records
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: finops-foundation.listcostandusage
      with:
        billingPeriodStart: tools.billingPeriodStart
        billingPeriodEnd: tools.billingPeriodEnd
        chargeCategory: tools.chargeCategory
        providerName: tools.providerName
        serviceName: tools.serviceName
        serviceCategory: tools.serviceCategory
        region: tools.region
        resourceId: tools.resourceId
        subAccountId: tools.subAccountId
        billingCurrency: tools.billingCurrency
        pageSize: tools.pageSize
        pageToken: tools.pageToken
      inputParameters:
      - name: billingPeriodStart
        type: string
        description: Filter by billing period start date (inclusive). Format is date-time per RFC 3339.
      - name: billingPeriodEnd
        type: string
        description: Filter by billing period end date (exclusive). Format is date-time per RFC 3339.
      - name: chargeCategory
        type: string
        description: Filter by charge category (e.g., Usage, Purchase, Tax, Credit, Adjustment).
      - name: providerName
        type: string
        description: Filter by the name of the entity that made the resource or service available.
      - name: serviceName
        type: string
        description: Filter by the display name of the service that was purchased.
      - name: serviceCategory
        type: string
        description: Filter by the highest-level classification of a service (e.g., Compute, Storage, Networking, Database).
      - name: region
        type: string
        description: Filter by the isolated geographic area where a resource is provisioned or a service is provided.
      - name: resourceId
        type: string
        description: Filter by unique identifier assigned to a resource by the provider.
      - name: subAccountId
        type: string
        description: Filter by the identifier for a sub account.
      - name: billingCurrency
        type: string
        description: Filter by the currency that a charge was billed in.
      - name: pageSize
        type: integer
        description: Number of records to return per page.
      - name: pageToken
        type: string
        description: Token for retrieving the next page of results.
      outputParameters:
      - type: object
        mapping: $.
    - name: exportcostandusage
      description: FinOps Foundation Export cost and usage data
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: finops-foundation.exportcostandusage
      outputParameters:
      - type: object
        mapping: $.
    - name: getcostandusageexportstatus
      description: FinOps Foundation Get cost and usage export job status
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: finops-foundation.getcostandusageexportstatus
      with:
        jobId: tools.jobId
      inputParameters:
      - name: jobId
        type: string
        description: The unique identifier for the export job.
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: listcontractcommitments
      description: FinOps Foundation List contract commitment records
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: finops-foundation.listcontractcommitments
      with:
        commitmentDiscountId: tools.commitmentDiscountId
        billingAccountId: tools.billingAccountId
        pageSize: tools.pageSize
        pageToken: tools.pageToken
      inputParameters:
      - name: commitmentDiscountId
        type: string
        description: Filter by the identifier assigned to a commitment discount by the provider.
      - name: billingAccountId
        type: string
        description: Filter by the unique identifier for a billing account.
      - name: pageSize
        type: integer
        description: Number of records to return per page.
      - name: pageToken
        type: string
        description: Token for retrieving the next page of results.
      outputParameters:
      - type: object
        mapping: $.
    - name: getschemametadata
      description: FinOps Foundation Get FOCUS schema metadata
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: finops-foundation.getschemametadata
      outputParameters:
      - type: object
        mapping: $.
binds:
- namespace: env
  keys:
    FINOPS_FOUNDATION_TOKEN: FINOPS_FOUNDATION_TOKEN