Exporting usage data in FOCUS format

Export your IBM Cloud® usage data in FinOps Open Cost & Usage Specification (FOCUS) format to simplify multi-cloud cost management and enable seamless integration with FinOps tools.

The FOCUS format is a cross-cloud standard developed by the FinOps Foundation that normalizes billing and usage data across cloud providers. IBM Cloud now supports FOCUS v1.2 (FinOps Open Cost and Usage Specification) format for cost and usage reporting. By exporting your IBM Cloud usage data in FOCUS format, you can analyze IBM Cloud costs alongside AWS, Azure, and GCP data without custom transformation. For more information, see the FinOps Foundation FOCUS v1.2 specification.

Before you begin

Before you export usage data in FOCUS format, ensure that you have the following access and resources:

  • Billing Administrator or Account Owner access to the IBM Cloud account
  • Access to the IBM Cloud console or CLI
  • Understanding of your cost management and FinOps tool requirements

Understanding FOCUS format benefits

The FOCUS format provides several advantages for managing your cloud costs:

Enhanced multi-cloud visibility
Normalize IBM Cloud usage data with AWS Cost and Usage Reports (CUR), Azure CSV exports, and GCP billing data for unified cost analysis.
Direct tool integration
Import FOCUS-formatted data directly into FinOps platforms such as Apptio Cloudability, CloudHealth, Kubecost, and other cost optimization tools without custom transformation scripts.
Reduced onboarding time
Eliminate manual data transformation processes, reducing the time and cost required to integrate IBM Cloud billing data into your cost management workflows.
Improved transparency
Access standardized billing dimensions that align with industry best practices, making it easier to understand and validate your IBM Cloud charges.
Competitive parity
Benefit from the same standardized format used by other leading cloud service providers, ensuring consistent cost management practices across your multi-cloud environment.

Exporting usage data

Instance-level usage data provides granular details about individual resource instances, enabling detailed cost allocation and chargeback.

  1. Log in to the IBM Cloud console.
  2. Go to Manage > Billing and usage > Usage.
  3. Click FOCUS button. The system downloads a CSV file containing instance-level usage data in FOCUS v1.2 format, with additional columns for resource-specific details.

Fully Supported Fields

IBM CSV file includes all mandatory FOCUS v1.2 fields:

Fully supported MUST fields
Field Type Description
BilledCost Decimal Cost billed to customer
BillingCurrency String Currency code (ISO 4217)
ChargeCategory String Type of charge (Usage, Purchase, Tax, Adjustment)
ChargeDescription String Description of the charge
ChargePeriodEnd DateTime End of charge period (ISO 8601)
ChargePeriodStart DateTime Start of charge period (ISO 8601)
EffectiveCost Decimal Amortized cost after discounts
ListUnitPrice Decimal List price per unit before discounts
PricingCategory String Pricing model
PricingQuantity Decimal Quantity used for pricing
PricingUnit String Unit of measure for pricing
ProviderName String Always "IBM"
PublisherName String Service publisher name
ResourceId String Unique resource identifier
ResourceName String Resource name
ServiceCategory String High-level service category
ServiceName String Name of the service
SkuId String SKU identifier

Additional Supported Fields

Beyond the 16 mandatory fields, IBM Cloud FOCUS reports include 39 additional fields:

Additional supported fields
Category Field Name
Account & Billing: BillingAccountId, BillingAccountName, BillingAccountType, BillingPeriodEnd, BillingPeriodStart, InvoiceIssuerName
Geographic: AvailabilityZone, RegionId, RegionName
Commitment & Discount: CommitmentDiscountCategory, CommitmentDiscountId, CommitmentDiscountName, CommitmentDiscountType, CommitmentDiscountUnit
Cost Breakdown: ContractedCost, ContractedUnitPrice, ListCost
Charge Details: ChargeClass, ChargeFrequency
Consumption: ConsumedQuantity, ConsumedUnit
Pricing: PricingCurrency, SkuMeter
Resource Metadata: ResourceType, ServiceSubcategory, Tags
IBM-Specific Extensions: x_DiscountId, x_DiscountName, x_DiscountQuantity, x_OfferId, x_OfferCredit

Exporting usage data using the API

You can automate usage data exports using the IBM Cloud Usage Reports API. For more information, see Usage Reports API.

  1. Obtain an API key with appropriate billing access. For more information, see Managing API keys.

  2. Use the following API endpoint to export usage data:

    curl -X GET "https://billing.cloud.ibm.com/v4/accounts/{account_id}/focus/{month}" \
  -H "Authorization: Bearer {iam_token}" \
  -H "Accept: text/csv"

Replace {account_id} with your IBM Cloud account ID (required), {month} with the report month in YYYY-MM format (e.g., 2024-01), and {iam_token} with your IAM access token.

API parameters

The FOCUS export API supports the following parameters: account_id (required) : The IBM Cloud account ID.

month (required)
Report month in YYYY-MM format (e.g., 2024-01).

Headers: Authorization (required) : Bearer token for IAM authentication.

x-focus-version (optional)
FOCUS version to use (default: 1.2). Set to true to bypass cache and generate fresh report.

Query Parameters:

format
Options include:
  • json (default) - will return results in paginated JSON format.
  • csv - will return all results in CSV format.
_limit (optional)
Pagination limit, max 250 (default: 200).

Validating FOCUS format exports:

To ensure your exported data meets FOCUS v1.2 specifications, you can validate the files using the FOCUS validator tool from the FinOps Foundation. The IBM Cloud FOCUS exports are designed to pass validation with 100% compliance on all 16 mandatory MUST fields.

Comparing IBM native and FOCUS v1.2 formats

Both IBM native and FOCUS v1.2 formats are available for usage exports. The following table highlights key differences:

Format comparison
Aspect IBM Native Format FOCUS v1.2 Format
Column names IBM-specific naming conventions Standardized FOCUS v1.2 column names
Multi-cloud compatibility IBM Cloud only Compatible with AWS, Azure, GCP
FinOps tool support Requires custom transformation Direct import supported
Data granularity Same level of detail Same level of detail
Compliance IBM-specific 100% compliant with FOCUS v1.2 (16/16 MUST fields)
Use case IBM-specific analysis and reporting Multi-cloud cost management and FinOps tools

You can export data in both formats simultaneously to support different use cases within your organization.

Next steps

After exporting your usage data in FOCUS format, you can: