Where the numbers come from

txtop combines several data lanes without pretending they have the same authority. A number’s lane and provenance determine what it means and how it can be compared.

Four ingest paths

Provider API polling reads organization usage and reported billing data from OpenAI, Anthropic, and OpenRouter. This is the closest lane to provider billing, but it can require administrator credentials and may arrive at daily rather than request-level granularity.

Subscription scanning reads local Codex, Claude Code, and Gemini CLI session logs. It works without API credentials and gives useful personal history, but the upstream file formats are unofficial and the totals are not billing statements.

OpenTelemetry receives usage events emitted by coding agents or OpenRouter. Where OTEL and local logs describe the same request, correlation and source-specific preference prevent both copies from contributing to projected usage.

The Ollama proxy observes local requests and responses. Token counts are local; cost is an estimate only when a model mapping supplies reference pricing.

Billing lanes

Every projected event belongs to api, subscription, local, or unknown. An explicitly reported lane wins; otherwise txtop can infer one from the source policy and records that provenance.

The 1, 2, and 3 keys toggle API, subscription, and local series. Use them when two products or accounts should not be compared as one total.

Why totals can differ

Provider dashboards can use different time zones, late adjustments, cache-token rules, pricing revisions, or aggregation windows. Local logs can omit failed or older sessions, and telemetry can be disabled for part of a period. Backfill also means recent API totals may change after the first refresh.

Treat reported provider cost as authoritative for billing. Treat subscription and local cost as monitoring estimates, especially when model mappings or unofficial formats are involved. Diagnostics expose source health and projector lag when a comparison looks incomplete.

See compatibility and support for stability promises and unofficial integrations for the risk boundary.