What if my agent does not report cost_usd?

That call is recorded with unknown cost. Cost analysis estimates it from the model rates you enter; the savings page uses the built-in official price list when you have not entered rates and labels the total as including catalog estimates.

Does going over budget block my agents?

No. The monthly budget only shows a warning on screen.

AI agent token cost monitoring

How many calls each agent made, how many tokens it used, what it cost and how often it failed, split by project, agent and model.

How data gets in

MCP checkup: add Budgethelm to your AI tool, authorize once, and tell your agent "Run a Budgethelm checkup". It runs one command on your computer that reads the local Claude Code / Codex logs and uploads only timestamps, tool, model, token counts and stop records; conversations, files and API keys never leave your computer.
Ingest keys: create an ingest key (starting with aops_) in a project and have your agent send each call to POST /api/ingest/usage, up to 500 records per request. Re-sending the same external_id is not double-counted. The key is shown once and only its hash is stored.
CSV import: parsed and previewed in the browser with line-numbered errors, up to 5,000 rows at a time. The optional cache_read_tokens column lets Budgethelm check whether prompt caching is used.
Demo data: one click creates 14 days of data for 3 fictional agents, labelled as fictional and removable in one click.

What you can see

Overview: spend this week (vs. last week), the most expensive agent, and estimated monthly savings.
Project page: last 14 days of calls, tokens, known cost, error rate and average latency, a daily chart, splits by agent and model, and the 20 most recent calls.
Cost analysis: any date range, with cost estimated from the model rates you enter.
Monthly budget: this month's cost against budget. Going over shows a warning and never blocks agents.
Anomaly flags: each day's calls, cost and error rate are compared with the previous 7 days, and sudden spikes are highlighted on screen (no notifications yet).

How cost is calculated

If an agent reports cost_usd, Budgethelm adds it up as known cost. If not, the cost is recorded as unknown rather than guessed. Screens that estimate (cost analysis, savings) use the model rates you enter, and the savings page falls back to the built-in official price list, labelled as an estimate. Days are cut in UTC.

Ask from your AI tool

After connecting Budgethelm over MCP, call get_project_summary and get_cost_breakdown from Claude Code, Cursor or Codex. Access is granted per scope, and you can limit it to specific projects.

FAQ

What if my agent does not report cost_usd?: That call is recorded with unknown cost. Cost analysis estimates it from the model rates you enter; the savings page uses the built-in official price list when you have not entered rates and labels the total as including catalog estimates.
Does going over budget block my agents?: No. The monthly budget only shows a warning on screen.
Which time zone is used?: All days are cut in UTC.