Guide 33 of 61 · Cost
Reconcile spend with provider invoices
Reconcile a day of this machine's model calls against your provider's own usage and cost reports, read where they differ, and export FOCUS rows.
Built, not yet claimed preview: this guide describes a package that has not passed its release gate.
Give agentgarmd the admin key that reads your provider account's usage reports, reconcile a day of this machine's model calls against the provider's own usage and cost reports, read where the two differ and why, and export the day's cost as FOCUS rows for your FinOps tools.
1. Check that your provider has a connector
Reconciliation needs a connector for the provider's report API. There are five: Anthropic and OpenAI (usage and cost), Cursor and GitHub Copilot (billed amounts) and Devin (usage in credits or ACUs, with no money). OpenRouter has a report API but no connector yet, and the other providers have no report API, so their calls cannot be reconciled; cloud billing exports (AWS, Azure, GCP) are later work. Every connector is so far proven only against recorded responses, and its output says so.
On a machine, reconciliation keeps one account per provider and counts all of the provider's calls stored there as that account's, since a call does not carry its account. A machine enrolled in Central Lite refuses it: a fleet reconciles in Central Lite.
2. Enrol the provider's admin key
Each connector needs its own least-privilege report key, never the key your agents use: an Anthropic Admin API key (organisations only), an OpenAI Admin API key, a Cursor Admin API key (team plan), a Devin service user key with “Use Local Analytics API”, or a GitHub organisation administrator's token. The account is the organisation's UUID for Anthropic (Claude Console, Settings → Organization), the org-… id for OpenAI, the team id for Devin and the organisation's login for GitHub, and a run whose report names another account fails. For Cursor it is a name you give the team, which nothing checks.
agentgarmd costs key set reads the key from stdin, never an argument, seals it and records the change in the audit chain; the agentgarm CLI never holds it. One account per provider: --replace swaps in another. On a no-root install add --user after the account and drop sudo. agentgarmd costs key list names the providers and accounts with a key, and remove deletes one.
read -rs KEY && printf '%s' "$KEY" | sudo agentgarmd costs key set anthropic --account <organisation-uuid>; unset KEY3. Reconcile a day
agentgarm costs reconcile asks agentgarmd to fetch one provider account's reports for one UTC day, by default yesterday; a day that has not been over for an hour is refused, so a partial day never reads as drift. agentgarmd runs the fetch in a separate unprivileged process, checks every row it returns, reconciles them with the day's calls and records the result in the audit chain. Run it as root on a root install, or with --user on a no-root install, from outside any governed task. A run can take up to two minutes.
sudo agentgarm costs reconcile --provider anthropic --account <organisation-uuid>agentgarm costs reconcile --provider openai --account <org-id> --day 2026-10-29 --json --userSee also
Attribute AI spend by machine and personRead your enrolled machines' model spend by day, machine, provider and model, and reconcile it against your providers' own usage and cost reports.
4. Read the differences
The first line gives the status. within tolerance means the reconciled cost is within 1 % of the provider's billed (workspace) cost, less the lines AgentGarm excludes, such as Anthropic's batch and code-execution lines. DRIFT beyond the 1 % tolerance and FAILED exit 1; a failed run is recorded too, and the calls keep their own cost. no workspace cost to compare with is every Devin day, since Devin reports no money.
Below it come the local cost of this machine's calls, the reconciled cost (the report's usage priced from the catalog, and the local figure for any model the report lacks), the workspace cost with its excluded part, and the drift. Then one line per model with its local and report figures, a not in the report: line for each model the report lacks, and each excluded or unpriced item.
A line “adopted from the vendor's billed cost (not an independent check)” means part of the figure is the provider's own bill, which matches the bill by construction: all of Cursor's and GitHub Copilot's, whose agents run on their own backends, and Anthropic models with long-context rates. agentgarm status shows each account's last reconciled day and its status.
agentgarm status5. Find out why a day drifts
Some drift is known and not yet excluded. For Anthropic, flex and priority-on-demand usage is unpriced, yet its cost lines cannot be told apart from ordinary usage. For OpenAI, batch and Scale Tier cost lines cannot be told apart from ordinary ones, cache writes are unpriced, audio and image tokens are priced at text rates, web searches are priced at one rate although non-reasoning models bill more for them, and a model with long-context rates keeps the proxy's figure, so its calls that did not pass the proxy are missing. For a drift day outside these, compare the model lines and the excluded items to find the model that differs.
See also
See what each task costRoute an agent's model calls through AgentGarm so each one is counted and priced, and read the spend by provider and model.
6. Export the day's cost as FOCUS rows
Turn on the file export's focus stream in default.yaml, the only policy file whose export section is read, and restart agentgarmd. After each UTC day closes it writes focus-<day>.csv (FOCUS 1.5 draft) and focus-exclusions-<day>.csv (usage it cannot price, never dropped) into the export folder of its state directory, such as /var/lib/agentgarm/export on a root install on Linux. The first day written is the next one to close, and under the non-monitoring compliance profile no FOCUS row is written. Two keys share the name: focus: true under file switches the stream on, and the focus block beside file holds the billing accounts its rows name.
The rows are AgentGarm's own measurement of the stored calls at the catalog's list price, not the reconciled figures: ListCost carries the cost, and BilledCost and EffectiveCost are 0, because AgentGarm neither invoices nor originates the charge. Before merging them with the provider's own FOCUS export, select AgentGarm's rows by their x_AgentGarm columns, or the list cost and quantities are counted twice.
export:
file:
ocsf: false
otel: false
focus: true
focus:
billing_accounts:
anthropic: your-anthropic-organisation-uuid
openai: org-your-organisation-id