version: "1.0.3" 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

1. 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.
2. 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.
3. 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

1. Compute key metrics: Calculate:

• Total spend for the period
• Average daily cost
• Cost per conversation (if trackable)
• Projected monthly cost at current burn rate

1. Compare to budget: If a budget threshold is configured, compare current spend and projection against it. Flag if on track to exceed.
2. 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.