# Cost Report > Query and report on API usage costs across LLM, embedding, and tool providers Use when this capability is needed. - Skill: `tomevault-io/cost-report` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/cost-report` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/cost-report/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/cost-report --- # 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 Ollama, 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 4. **Compute key metrics**: Calculate: - Total spend for the period - Average daily cost - Cost per conversation (if trackable) - Projected monthly cost at current burn rate 5. **Compare to budget**: If a budget threshold is configured, compare current spend and projection against it. Flag if on track to exceed. 6. **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. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/quixiai) — claim your Tome and manage your conversions.