FinOps Foundation Cost and Usage API

openapi: 3.1.0
info:
  title: FinOps Foundation FOCUS Contract Commitments 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.
  version: 1.3.0
  contact:
    name: FinOps Foundation
    url: https://www.finops.org/
  license:
    name: Community Specification License 1.0
    url: https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/blob/main/LICENSE
  x-focus-version: '1.3'
servers:
- url: https://api.example.com/focus/v1
  description: Example FOCUS-compliant API server
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: Cost and Usage
  description: Endpoints for querying FOCUS-compliant cost and usage data, the primary dataset defined by the FOCUS specification.
paths:
  /cost-and-usage:
    get:
      operationId: listCostAndUsage
      summary: FinOps Foundation List cost and usage records
      description: Retrieves FOCUS-compliant cost and usage records. The response conforms to the FOCUS Cost and Usage dataset schema, providing normalized billing data with standardized columns for dimensions and metrics.
      tags:
      - Cost and Usage
      parameters:
      - name: billingPeriodStart
        in: query
        description: Filter by billing period start date (inclusive). Format is date-time per RFC 3339.
        required: false
        schema:
          type: string
          format: date-time
      - name: billingPeriodEnd
        in: query
        description: Filter by billing period end date (exclusive). Format is date-time per RFC 3339.
        required: false
        schema:
          type: string
          format: date-time
      - name: chargeCategory
        in: query
        description: Filter by charge category (e.g., Usage, Purchase, Tax, Credit, Adjustment).
        required: false
        schema:
          type: string
          enum:
          - Usage
          - Purchase
          - Tax
          - Credit
          - Adjustment
      - name: providerName
        in: query
        description: Filter by the name of the entity that made the resource or service available.
        required: false
        schema:
          type: string
      - name: serviceName
        in: query
        description: Filter by the display name of the service that was purchased.
        required: false
        schema:
          type: string
      - name: serviceCategory
        in: query
        description: Filter by the highest-level classification of a service (e.g., Compute, Storage, Networking, Database).
        required: false
        schema:
          type: string
      - name: region
        in: query
        description: Filter by the isolated geographic area where a resource is provisioned or a service is provided.
        required: false
        schema:
          type: string
      - name: resourceId
        in: query
        description: Filter by unique identifier assigned to a resource by the provider.
        required: false
        schema:
          type: string
      - name: subAccountId
        in: query
        description: Filter by the identifier for a sub account.
        required: false
        schema:
          type: string
      - name: billingCurrency
        in: query
        description: Filter by the currency that a charge was billed in.
        required: false
        schema:
          type: string
      - name: pageSize
        in: query
        description: Number of records to return per page.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 10000
          default: 1000
      - name: pageToken
        in: query
        description: Token for retrieving the next page of results.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A paginated list of FOCUS cost and usage records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostAndUsageResponse'
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /cost-and-usage/export:
    post:
      operationId: exportCostAndUsage
      summary: FinOps Foundation Export cost and usage data
      description: Initiates an export of FOCUS-compliant cost and usage data for a specified billing period. Returns a job identifier that can be used to check the status and retrieve the exported data.
      tags:
      - Cost and Usage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportRequest'
      responses:
        '202':
          description: Export job accepted and processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJobResponse'
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /cost-and-usage/export/{jobId}:
    get:
      operationId: getCostAndUsageExportStatus
      summary: FinOps Foundation Get cost and usage export job status
      description: Retrieves the status of a previously initiated cost and usage data export job.
      tags:
      - Cost and Usage
      parameters:
      - name: jobId
        in: path
        description: The unique identifier for the export job.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Export job status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJobResponse'
        '404':
          description: Export job not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CostAndUsageResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CostAndUsageRecord'
        nextPageToken:
          type: string
          description: Token to retrieve the next page of results. Null if no more pages.
          nullable: true
        totalRecords:
          type: integer
          description: Total number of records matching the query.
        dataLastUpdated:
          type: string
          format: date-time
          description: Timestamp indicating when the dataset was last updated.
        dataCompleteness:
          type: string
          enum:
          - Complete
          - Incomplete
          description: Indicates whether the data for the requested period is complete or subject to revision.
      required:
      - data
    ExportJobResponse:
      type: object
      properties:
        jobId:
          type: string
          description: The unique identifier for the export job.
        status:
          type: string
          enum:
          - Pending
          - Processing
          - Complete
          - Failed
          description: The current status of the export job.
        createdAt:
          type: string
          format: date-time
          description: When the export job was created.
        completedAt:
          type: string
          format: date-time
          nullable: true
          description: When the export job completed.
        downloadUrl:
          type: string
          format: uri
          nullable: true
          description: The URL to download the exported data. Only available when status is Complete.
        recordCount:
          type: integer
          nullable: true
          description: The total number of records in the export.
        error:
          type: string
          nullable: true
          description: Error message if the export job failed.
      required:
      - jobId
      - status
      - createdAt
    CostAndUsageRecord:
      type: object
      description: A single cost and usage record conforming to the FOCUS specification. Contains dimensions (qualitative values for categorization and filtering) and metrics (quantitative values for measurement).
      properties:
        AvailabilityZone:
          type: string
          nullable: true
          description: A provider-assigned identifier for a physically separated and isolated area within a region that provides high availability and fault tolerance.
        BilledCost:
          type: number
          description: A charge serving as the basis for invoicing, inclusive of the impacts of all reduced rates and discounts while excluding the amortization of relevant purchases. MUST NOT be null.
        BillingAccountId:
          type: string
          description: The unique identifier for a billing account. MUST NOT be null.
        BillingAccountName:
          type: string
          description: The display name assigned to a billing account.
        BillingCurrency:
          type: string
          description: The currency that a charge was billed in. Represented as a three-letter ISO 4217 currency code. MUST NOT be null.
        BillingPeriodEnd:
          type: string
          format: date-time
          description: The exclusive end date and time of the billing period. MUST NOT be null.
        BillingPeriodStart:
          type: string
          format: date-time
          description: The inclusive start date and time of the billing period. MUST NOT be null.
        CapacityReservationId:
          type: string
          nullable: true
          description: The identifier assigned to a capacity reservation by the provider. Introduced in FOCUS v1.3.
        ChargeCategory:
          type: string
          enum:
          - Usage
          - Purchase
          - Tax
          - Credit
          - Adjustment
          description: The highest-level classification of a charge based on the nature of how it is billed. MUST NOT be null.
        ChargeClass:
          type: string
          nullable: true
          enum:
          - Correction
          description: Indicates whether the row represents a correction to one or more charges invoiced in a previous billing period.
        ChargeDescription:
          type: string
          description: A self-contained summary of the charge's purpose and price.
        ChargeFrequency:
          type: string
          enum:
          - One-Time
          - Recurring
          - Usage-Based
          description: Indicates how often a charge will occur. MUST NOT be null.
        ChargePeriodEnd:
          type: string
          format: date-time
          description: The exclusive end date and time of a charge period. MUST NOT be null.
        ChargePeriodStart:
          type: string
          format: date-time
          description: The inclusive start date and time of a charge period. MUST NOT be null.
        CommitmentDiscountCategory:
          type: string
          nullable: true
          enum:
          - Spend
          - Usage
          description: Indicates whether the commitment discount is based on usage quantity or cost.
        CommitmentDiscountId:
          type: string
          nullable: true
          description: The identifier assigned to a commitment discount by the provider.
        CommitmentDiscountName:
          type: string
          nullable: true
          description: The display name assigned to a commitment discount.
        CommitmentDiscountQuantity:
          type: number
          nullable: true
          description: The amount of a commitment discount purchased or accounted for in commitment discount-related rows.
        CommitmentDiscountStatus:
          type: string
          nullable: true
          enum:
          - Used
          - Unused
          description: Indicates whether the charge corresponds to the consumption of a commitment discount or the unused portion.
        CommitmentDiscountType:
          type: string
          nullable: true
          description: A provider-assigned label describing the type of commitment discount (e.g., Reserved Instance, Savings Plan).
        CommitmentDiscountUnit:
          type: string
          nullable: true
          description: The provider-specified measurement unit for the commitment discount quantity.
        ConsumedQuantity:
          type: number
          nullable: true
          description: The volume of a given resource or service used, based on the consumed unit.
        ConsumedUnit:
          type: string
          nullable: true
          description: The provider-specified measurement unit indicating how a resource or service was consumed.
        ContractedCost:
          type: number
          description: The cost calculated by multiplying contracted unit price and the corresponding pricing quantity. MUST NOT be null.
        ContractedUnitPrice:
          type: number
          nullable: true
          description: The agreed-upon unit price for a single pricing unit of the associated resource or service.
        EffectiveCost:
          type: number
          description: The amortized cost of the charge after applying all reduced rates, discounts, and the applicable portion of relevant prepaid purchases. MUST NOT be null.
        InvoiceIssuerName:
          type: string
          description: The name of the entity responsible for invoicing for the resources or services consumed. MUST NOT be null.
        ListCost:
          type: number
          description: The cost calculated by multiplying list unit price and the corresponding pricing quantity. MUST NOT be null.
        ListUnitPrice:
          type: number
          nullable: true
          description: The suggested provider-published unit price for a single pricing unit of the associated resource or service.
        PricingCategory:
          type: string
          nullable: true
          enum:
          - On-Demand
          - Commitment-Based
          - Dynamic
          - Other
          description: Describes the pricing model used for a charge at the time of use or purchase.
        PricingQuantity:
          type: number
          nullable: true
          description: The volume of a given resource or service used or purchased, based on the pricing unit.
        PricingUnit:
          type: string
          nullable: true
          description: The provider-specified measurement unit for determining unit prices and pricing quantities.
        ProviderName:
          type: string
          description: The name of the entity that made the resource or service available for purchase. MUST NOT be null.
        PublisherName:
          type: string
          description: The name of the entity that produced the resource or service that was purchased.
        Region:
          type: string
          nullable: true
          description: An isolated geographic area where a resource is provisioned in or a service is provided from.
        ResourceId:
          type: string
          nullable: true
          description: The unique identifier assigned to a resource by the provider.
        ResourceName:
          type: string
          nullable: true
          description: The display name assigned to a resource.
        ResourceType:
          type: string
          nullable: true
          description: The type of resource the charge applies to.
        ServiceCategory:
          type: string
          description: The highest-level classification of a service based on the core function of the service (e.g., Compute, Storage, Networking, Database). MUST NOT be null.
        ServiceName:
          type: string
          description: The display name of the service that was purchased. MUST NOT be null.
        ServiceSubcategory:
          type: string
          nullable: true
          description: A secondary classification of a service, providing further detail beyond ServiceCategory.
        SkuId:
          type: string
          nullable: true
          description: The unique identifier for the SKU that was used or purchased.
        SkuPriceId:
          type: string
          nullable: true
          description: The unique identifier for the SKU inclusive of all pricing variations such as tiering and discounts.
        SubAccountId:
          type: string
          nullable: true
          description: The identifier assigned to a grouping of resources or services, often used to manage access and/or cost.
        SubAccountName:
          type: string
          nullable: true
          description: The display name assigned to a sub account.
        Tags:
          type: object
          nullable: true
          additionalProperties:
            type: string
          description: A set of key-value pairs applied to a resource. Tags are commonly used for cost allocation, access control, and automation.
        x_SplitCostAllocationMethod:
          type: string
          nullable: true
          description: The method used by the data generator for split cost allocation across workloads. Introduced in FOCUS v1.3.
        x_SplitCostAllocationPercentage:
          type: number
          nullable: true
          description: The percentage of the cost allocated to this record via split cost allocation. Introduced in FOCUS v1.3.
      required:
      - BilledCost
      - BillingAccountId
      - BillingCurrency
      - BillingPeriodEnd
      - BillingPeriodStart
      - ChargeCategory
      - ChargeFrequency
      - ChargePeriodEnd
      - ChargePeriodStart
      - ContractedCost
      - EffectiveCost
      - InvoiceIssuerName
      - ListCost
      - ProviderName
      - ServiceCategory
      - ServiceName
    Error:
      type: object
      properties:
        code:
          type: string
          description: A machine-readable error code.
        message:
          type: string
          description: A human-readable error message.
        details:
          type: string
          nullable: true
          description: Additional details about the error.
      required:
      - code
      - message
    ExportRequest:
      type: object
      properties:
        billingPeriodStart:
          type: string
          format: date-time
          description: The inclusive start of the billing period to export.
        billingPeriodEnd:
          type: string
          format: date-time
          description: The exclusive end of the billing period to export.
        format:
          type: string
          enum:
          - csv
          - parquet
          - json
          default: csv
          description: The output format for the exported data.
        includeContractCommitments:
          type: boolean
          default: false
          description: Whether to include contract commitment data in the export.
      required:
      - billingPeriodStart
      - billingPeriodEnd
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication for FOCUS API access.
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key authentication for FOCUS API access.
externalDocs:
  description: FOCUS Specification v1.3
  url: https://focus.finops.org/focus-specification/v1-3/