| name | cost-report |
| description | Query and report on API usage costs across LLM, embedding, and tool providers |
| category | analytics |
| requires | {"tools":["query_usage"]} |
| contexts | ["heartbeat","chat"] |
| aliases | ["cost","costs","spend","spent","usage","tokens","budget","bill","billing"] |
| bound_tools | ["query_usage"] |
Usage Cost Reporting
Query the API usage ledger and produce clear, actionable cost reports broken down by provider, model, and time period.
When to Use
- When the user asks "how much have I spent" or "show me my usage"
- During heartbeats to check if spending is approaching a configured budget threshold
- When evaluating whether to switch models or providers based on cost efficiency
- As part of a daily or weekly briefing that includes operational metrics
- After a heavy ingestion or research session to assess the cost impact
Step-by-Step Methodology
- Determine the time window: Default to the current billing period (calendar month) unless the user specifies a range. Common windows: today, this week, this month, last 30 days, custom range.
- Query the ledger: Use
query_usage with the appropriate date range. The tool returns rows from the api_usage table with provider, model, token counts (input/output), and computed cost.
- Aggregate by dimension: Break down the raw data into useful summaries:
- By provider: Total cost per provider (OpenAI, Anthropic, local inference, etc.)
- By model: Cost per model to identify which models consume the most budget
- By category: Separate LLM inference costs from embedding costs from tool API costs
- By day: Daily trend to spot spikes or patterns
- Compute key metrics: Calculate:
- Total spend for the period
- Average daily cost
- Cost per conversation (if trackable)
- Projected monthly cost at current burn rate
- Compare to budget: If a budget threshold is configured, compare current spend and projection against it. Flag if on track to exceed.
- Present the report: Format as a clean table or summary. Lead with the headline number (total spend), then break down by the most useful dimension.
Quality Guidelines
- Always show actual numbers, not vague descriptions. "You have spent $4.32 this month" is useful; "you have moderate usage" is not.
- Round costs to two decimal places for readability.
- When projecting monthly cost, note that it is an extrapolation and actual spend may vary.
- If the usage ledger is empty or the query returns no data, say so plainly rather than reporting zeros that could be misleading.
- In heartbeat context, only generate a cost report if spend is approaching a threshold or if a goal explicitly asks for cost monitoring. Do not waste energy on routine cost checks every heartbeat.
- Protect cost data as operational metadata. Do not expose it to external services.
