query_unit_costs
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 unless cost_metric is "amortized", which spreads prepaid commitments across the term they cover (see query_costs). Budgets and the target_unit_cost alert stay billed either way. 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. When the metric has a denominator_dimension_key (e.g. "feature") the "customer" in those rows is that dimension's value, matched against the tag values of the numerator's tag key.
A metric with revenue_source_ids also returns revenue (billed revenue in the USD base, from connected revenue streams only) and gross_margin_pct on every row. Both are null when the period has no revenue rows; that is missing data, not a margin of zero.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | No | ISO-8601 end of the date range (exclusive) | |
| group_by | No | Time bucket size (default: day) | |
| start_date | No | ISO-8601 start of the date range (inclusive) | |
| cost_metric | No | Which cost figure feeds the numerator (default: "billed"). Same meaning as on query_costs. | |
| unit_metric_id | Yes | id of a metric returned by list_unit_metrics |