FinOps Foundation Cost and Usage API

openapi: 3.2.0
info:
  title: 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.
  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:
    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
    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
    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
    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
  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/