query_unit_costs

com.plutus-cloud/plutus-cost-data · Verify this server

Compute one of this account's saved unit-economics metrics (see list_unit_metrics) over a date range — the cost of a slice of spend divided by the business units it produced. Each row carries `cost` (the numerator, in the USD base like every other figure this server returns), `quantity` (the denominator, a raw count with no currency), and `unit_cost`. CRITICAL: `unit_cost` is null whenever it could not be computed, and null does NOT mean zero. It means one half of the fraction is missing for that period — either no usage was ingested (a telemetry gap) or no cost data has landed yet. Do not describe a null unit cost as a cost of zero, and do not average nulls in as zeroes; the `coverage` block reports how many rows are affected and why. Always read `unit_cost` together with `denominator_label` (e.g. "per 1k requests"), which names what it is quoted against — a per-1k figure reported as a per-request figure is wrong by three orders of magnitude. The series stops at `coverage.complete_through` rather than at the requested end_date whenever cost data for the newest periods has not arrived yet (it lands hours-to-a-day after the period it covers, while usage telemetry is pushed live). A short series is therefore normal and is NOT evidence that spend or usage stopped — say what it is complete through instead. `coverage.lagging_sources`, when non-empty, is the opposite case: a cost source that is behind or has stopped reporting, so recent periods are missing its spend and their unit costs read lower than the truth. If `numerator_status.available` is false, the cost source this metric measured has been removed from the account and `rows` is empty. That is a broken definition, not a period of zero spend — never report it as costs having fallen. Amounts are billed cost, never amortized, regardless of any cost_metric used elsewhere. A tag-scoped metric inherits that tag_key's allocation policy, so its numerator may include a redistributed share of shared spend (see list_cost_tags' redistribute_bucket) and will not match a raw dimension total. A metric whose denominator_mode is "per_customer" returns one row per (period, customer) and a `customers` block splitting them into matched, cost_without_usage (spend attributed to a customer who is not sending telemetry) and usage_without_cost (telemetry from a customer whose spend is not being allocated). Those two lists are the honest caveat on any per-customer figure and are worth mentioning when either is non-empty.