Cost data

GET /v1/finops/costs exports provider-reported billed costs for an authorized account.

GET /v1/finops/costs?start=2026-07-01T00:00:00Z&end=2026-07-08T00:00:00Z&limit=1000
Authorization: Bearer <credential>

Usage and costs may differ in granularity, dimensions, retention, and freshness.

Billed cost semantics

BilledCost follows FOCUS 1.4 semantics: the provider-reported amount in BillingCurrency after applicable pricing adjustments. It must not be an estimate from a public rate card.

EffectiveCost equals BilledCost for simple pay-as-you-go usage. It may differ for commitments, prepaid credits, quota coverage, or amortization.

Money fields are JSON decimal strings (not integers). Consumers convert to fixed-point storage after parsing.

For non-USD billing:

• BilledCost stays in BillingCurrency
• PricingCurrency / PricingCurrencyBilledCost should carry a provider-computed USD equivalent when available
• Consumers must not invent an exchange rate and label it billed cost

Status

x_CostStatus:

• provisional: amount may be restated
• final: settled for the represented billing state

Quota-covered or commitment-covered amounts should use FOCUS charge classes / effective-cost semantics rather than inventing model-level allocations. Prefer less-detailed truthful cost over fabricated per-key allocations unless the row is explicitly identified as an allocation.

Corrections

• Open-period restatements update the same x_RecordId and advance x_RecordUpdatedAt
• Closed-period corrections should use a new negative Credit or Adjustment with x_CorrectsRecordId when known

Rate limiting, freshness, retention

Declare retention, max query windows, and settlement lag in capabilities. Send Retry-After on 429 / temporary 503. Prefer RFC 9331 rate-limit headers when practical.

as_of and available_through on paged responses tell clients which snapshot they traversed and how fresh complete periods are.