Provider Usage and Cost Management
GEO records provider usage at the workspace boundary. The usage ledger answers which provider and model was called, which GEO workflow initiated the call, how many tokens and provider-native web searches were reported, and how the estimated cost was derived.
Usage reporting is operational metering, not a provider invoice or Tenant billing statement. Provider invoices remain authoritative because vendors can apply negotiated rates, free tiers, batch discounts, regional taxes, rounding, and fees that are not present in an API response.
Metered operations
One usage event is created for every direct provider call initiated by:
- manual or scheduled monitoring observations;
- Explore discovery;
- Action Plan generation;
- provider connection tests.
Each event is bound to an Organization, Tenant, Workspace, and provider. Scope checks reject a provider that does not belong to the same Workspace. Deleting a provider prevents future calls but preserves its historical usage records.
Fixture, MCP, and RAG trace-ingestion connectors are not billed as direct model-provider calls by this ledger.
Provider pricing configuration
Configure pricing independently for every workspace provider:
| Field | Unit | Behavior |
|---|---|---|
| Input price | One million input tokens | Applied to the provider-reported input-token count |
| Output price | One million output tokens | Applied to the provider-reported output-token count |
| Web-search price | One provider-reported search request | Added only when the provider exposes a search-request count |
| Currency | Three-letter code such as USD or EUR | Stored on each usage event |
Use the rates from the workspace owner's provider contract. GEO does not silently replace a configured rate with a current public list price, because model prices and commercial terms can change.
For configured pricing, GEO calculates:
input cost = input tokens / 1,000,000 × input rate
output cost = output tokens / 1,000,000 × output rate
search cost = web-search requests × search rate
estimated total = input cost + output cost + search cost
For example, 1,000,000 input tokens at 2.50, 500,000 output tokens at 10.00, and two searches at 0.01 produce an estimated total of 7.52 in the configured currency.
Pricing-source states
| State | Meaning |
|---|---|
provider_reported | The provider returned a total cost; GEO uses it instead of the configured estimate |
configured | GEO calculated the total from the workspace-provider rates |
unpriced | The provider returned no total and no applicable configured rate exists |
A zero rate does not prove that the operation was free. Unpriced records remain visible so missing pricing cannot be mistaken for confirmed zero spend. Costs in different currencies remain separate and are never summed into a synthetic total.
Normalized provider usage
The observation runtime normalizes the supported provider contracts into:
- input tokens;
- output tokens;
- cached input tokens;
- reasoning tokens;
- provider-reported web-search requests;
- provider-reported total cost, when available.
Normalization covers OpenAI Responses and Chat Completions, Anthropic Messages, Perplexity, and Gemini usage metadata. Cached and reasoning counts are retained as additional dimensions; input and output pricing continues to use the provider's reported input and output totals.
Raw-response retention is independent. A connector may discard the raw provider payload while GEO still retains normalized usage required for operations and cost analysis.
Provider-native web search
Direct OpenAI, Anthropic Claude, Perplexity, and Google Gemini profiles can expose provider-native search or grounding. Generic OpenAI-compatible and custom providers cannot enable this capability merely by claiming compatibility.
When search is enabled, the adapter uses the selected provider's native contract and preserves structured citations. Market and location context is mapped only where the provider supports it. Provider-native search can add tool, request, retrieval-token, and model-token charges; configure the search rate from the applicable provider contract.
An API observation is not automatically equivalent to the provider's consumer application. Do not label an OpenAI API result as a ChatGPT consumer-surface observation, a Gemini API result as Google AI Overview, or any provider API as an otherwise closed product surface.
Provider Usage dashboard
Open Provider Usage under AI Systems inside a Workspace. Every summary, trend, breakdown, and record uses the same selected scope. The page provides:
- 7-day, 30-day, 90-day, and one-year windows;
- an inclusive custom date range;
- provider, GEO operation, and status filters;
- provider request count;
- input, output, and cached-token summaries;
- provider-reported web-search request count;
- metered Service Usage event volume;
- completed provider-request success rate;
- estimated cost separated by currency;
- explicit unpriced-record count;
- daily request trend;
- provider and operation breakdowns;
- recent records with model, status, tokens, searches, cost, and timestamp.
The dashboard reflects recorded provider events only. It does not infer missing tokens, searches, or prices and does not reconcile a vendor invoice.
Failure and retention behavior
Completed, error, timeout, and blocked statuses are visible. A provider error can have zero reported tokens because not every provider returns usage on a failed request. Existing answer evidence and usage events remain immutable when a run is replayed.
Usage persistence does not expose credentials or raw prompts in its metadata. If metering persistence fails after a provider response, the provider operation is not converted into a false failure; operators must alert on the metering error and investigate the resulting ledger gap.
Operational checklist
- Configure provider-specific rates and currency before a representative test.
- Run the provider connection test and one bounded monitoring prompt.
- Confirm the Usage page shows the correct workspace, provider, model, operation, and status.
- Compare normalized token and search counts with the provider response or console.
- Confirm the pricing source is
provider_reported,configured, or intentionallyunpriced. - Verify different currencies remain separate.
- Exercise an unauthorized cross-workspace provider ID and confirm that it fails closed.
- Compare estimates with the provider invoice periodically and update workspace rates when the contract changes.