openapi: 3.1.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. 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' externalDocs: description: FOCUS Specification v1.3 url: https://focus.finops.org/focus-specification/v1-3/ servers: - url: https://api.example.com/focus/v1 description: Example FOCUS-compliant API server tags: - name: Contract Commitments description: >- Endpoints for querying contract commitment data, a supplemental dataset introduced in FOCUS v1.3 that isolates contract terms from cost and usage rows. - name: Cost and Usage description: >- Endpoints for querying FOCUS-compliant cost and usage data, the primary dataset defined by the FOCUS specification. - name: Schema Metadata description: >- Endpoints for retrieving metadata about the FOCUS dataset schema, including column definitions, data types, and version information. 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' /contract-commitments: get: operationId: listContractCommitments summary: FinOps Foundation List contract commitment records description: >- Retrieves contract commitment records as defined in the FOCUS v1.3 supplemental dataset. Contract commitments isolate contract terms such as start and end dates, remaining units, and descriptions from cost and usage rows. tags: - Contract Commitments parameters: - name: commitmentDiscountId in: query description: Filter by the identifier assigned to a commitment discount by the provider. required: false schema: type: string - name: billingAccountId in: query description: Filter by the unique identifier for a billing account. 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 contract commitment records. content: application/json: schema: $ref: '#/components/schemas/ContractCommitmentResponse' '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' /schema: get: operationId: getSchemaMetadata summary: FinOps Foundation Get FOCUS schema metadata description: >- Retrieves metadata about the FOCUS dataset schema, including column definitions, data types, FOCUS version, and data generator version information. tags: - Schema Metadata responses: '200': description: FOCUS schema metadata. content: application/json: schema: $ref: '#/components/schemas/SchemaMetadata' '401': description: Authentication required. content: application/json: schema: $ref: '#/components/schemas/Error' components: 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. 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 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 ContractCommitmentResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/ContractCommitmentRecord' nextPageToken: type: string nullable: true description: Token to retrieve the next page of results. totalRecords: type: integer description: Total number of records matching the query. required: - data ContractCommitmentRecord: type: object description: >- A contract commitment record as defined in FOCUS v1.3. Isolates contract terms including start and end dates, remaining units, and descriptions from cost and usage rows. properties: CommitmentDiscountId: type: string description: >- The unique identifier assigned to a commitment discount by the provider. MUST NOT be null. CommitmentDiscountName: type: string nullable: true description: >- The display name assigned to a commitment discount. CommitmentDiscountType: type: string nullable: true description: >- A provider-assigned label describing the type of commitment discount. CommitmentDiscountCategory: type: string enum: - Spend - Usage description: >- Whether the commitment discount is based on usage quantity or cost. CommitmentStartDate: type: string format: date-time description: >- The start date and time of the contract commitment. CommitmentEndDate: type: string format: date-time description: >- The end date and time of the contract commitment. CommitmentTotalQuantity: type: number nullable: true description: >- The total quantity of the commitment purchased. CommitmentRemainingQuantity: type: number nullable: true description: >- The remaining quantity of the commitment that has not yet been consumed. CommitmentUnit: type: string nullable: true description: >- The unit of measurement for the commitment quantity. CommitmentDescription: type: string nullable: true description: >- A human-readable description of the contract commitment. BillingAccountId: type: string description: >- The unique identifier for the billing account associated with the commitment. BillingAccountName: type: string nullable: true description: >- The display name for the billing account. ProviderName: type: string description: >- The name of the entity that made the commitment discount available. required: - CommitmentDiscountId - CommitmentStartDate - CommitmentEndDate - BillingAccountId - ProviderName 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 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 SchemaMetadata: type: object description: >- Metadata about the FOCUS dataset schema, supporting communication of important attributes about the data including column names, data types, FOCUS version, and data generator version. properties: focusVersion: type: string description: The version of the FOCUS specification the data conforms to. example: '1.3' dataGeneratorName: type: string description: The name of the data generator producing the FOCUS data. dataGeneratorVersion: type: string description: The version of the data generator. columns: type: array items: $ref: '#/components/schemas/ColumnDefinition' description: List of column definitions in the FOCUS dataset. datasets: type: array items: type: string description: The datasets available from this data generator. example: - CostAndUsage - ContractCommitment required: - focusVersion - columns ColumnDefinition: type: object properties: columnName: type: string description: The name of the column. dataType: type: string enum: - String - Number - DateTime - JSON description: The data type of the column. requirement: type: string enum: - Must - Recommended - Optional description: >- The requirement level of the column per the FOCUS specification. nullable: type: boolean description: Whether the column can contain null values. description: type: string description: A description of the column and its purpose. category: type: string enum: - Dimension - Metric description: Whether this column is a dimension or a metric. required: - columnName - dataType - requirement - nullable 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 security: - bearerAuth: [] - apiKeyAuth: []