query_spend
Query LLM spending grouped by provider, model, project, tag, or day over a customizable time window, with optional filters to narrow results.
Instructions
Return spending broken down by a chosen axis over a time window.
start and end are ISO-8601 strings (trailing-Z, +00:00, or
naive — naive is interpreted as UTC). Default window is the last
30 days. group_by is one of provider | model | project | tag | day.
filter AND-combines optional provider/model/project equality
predicates.
include_failed defaults to False so failure rows (e.g. streams
that died mid-flight with partial counts) are excluded from totals
and groups. Pass True to fold them back in — useful for debugging
capture-layer behavior, not for honest spend numbers.
Tag semantics: events with NULL/empty tags are excluded from
group_by="tag" results entirely; multi-tag events contribute once
per tag (so per-group calls sums can exceed the window total).
Project semantics are symmetric: NULL projects are dropped from
group_by="project". Groups are ordered cost-desc with
alphabetical ties.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | ||
| start | No | ||
| filter | No | ||
| group_by | No | provider | |
| include_failed | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| groups | Yes | ||
| total_calls | Yes | ||
| total_cost_usd | Yes | ||
| total_input_tokens | Yes | ||
| total_output_tokens | Yes |