query_costs

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

Query time-bucketed spend for this account, optionally broken down by a dimension (service, region, linked_account, usage_type, operation, or identity) or by a custom cost-allocation tag (see list_cost_tags), and filtered by dimension values. `identity` is per-actor spend (e.g. an OpenAI or Anthropic api_key_id) where a provider's cost/usage API can group by it; not every provider populates it. Mirrors the GET /api/analytics endpoint used by the Plutus dashboard charts. All amounts are in USD, converted from each provider's own billing currency at the rate in effect on the day of the charge; the response states this in its `currency` field. A row carries `cost_basis` only when its `cost` figure is an estimate rather than a real invoiced charge — e.g. Anthropic's identity-grain rows, priced from Anthropic's own published per-token rates because Anthropic's cost API has no per-key breakdown at all. Absent (null) `cost_basis` means the figure is invoiced. Always qualify an estimated figure as such when relaying it — do not present it with the same confidence as an invoiced one. Where a provider reports usage alongside cost, a row also carries `quantity` and its `unit` (e.g. tokens, GB-month), plus a derived `cost_per_unit` in that same USD base. Always read `cost_per_unit` together with `cost_per_unit_label`, which names the denominator it is quoted against: token costs are quoted per 1,000 tokens ("per 1k tokens", `cost_per_unit_scale: 1000`), NOT per single token. All four fields are null when the provider reports no usage, and also when the rows behind a group carry more than one unit — a total mixing tokens and GB-month is not a quantity, so none is given. The response also carries `coverage.complete_through`: cost data for the newest periods often has not landed yet (it arrives hours-to-a-day after the period it covers), so `rows` may end before `end_date` without that being a gap in spend — the newest period(s) simply aren't complete yet. `coverage.lagging_sources`, when non-empty, names a cost source that is behind or has stopped reporting; recent periods will under-count its spend. Unlike query_unit_costs, `rows` is NOT truncated to the horizon here — treat complete_through as a caveat on the newest bucket(s), not evidence anything is missing from the rows themselves.