Token use and cost (operator)

For whoever runs the box. This is about answering: “what is this costing, and where is it going?”

The useful unit: tokens

Lowkey records usage at the end of each agent turn. The record includes the conversation, turn, agent, provider, start and finish time, input tokens, output tokens, wall-clock time, tool calls, tool errors, and whether the token count is full or partial.

That makes the cost question practical even when the providers bill differently. Some providers expose exact per-token usage. Some run through subscription-style accounts where a clean dollar number is not meaningful. So Lowkey treats tokens and time as the stable baseline: enough to see whether a routine suddenly got heavy, whether one provider is carrying most of the work, or whether one conversation is burning far more context than expected.

Where you can see it

In a conversation, each completed turn can show a compact token label, such as ~18K in / 2.1K out. The conversation also keeps the ledger records in its session log, so the visible labels are backed by the same durable history the agent used.

In Settings -> Providers, each provider card can show total turns, input tokens, output tokens, and wall-clock time across projects. This is the fastest operator view for “which provider is doing the spending?”

In Automations, each routine can show average tokens over recent runs, and an individual run can show the tokens used by work owned by that run. This is the view to check when a scheduled job gets expensive or starts doing more model work than you expected.

Lowkey also writes rollups by conversation, day, agent, provider, and routine. Provider, conversation, and routine totals already have UI surfaces. Agent and daily rollups exist in the backend for reporting and support tooling, but they do not yet have a dedicated operator screen.

Rebuilding the numbers

Usage rollups are derived files, not the source of truth. The source is the canonical session log under the project, including each turn’s ledger event. If rollup files are missing or stale after an upgrade, the operator can rebuild them with:

lowkey usage rebuild --project /path/to/project

That command asks the daemon to reread the session logs and recreate the usage rollups. It does not rerun the agents or change the conversation history.

Staying in control

Treat usage as an early warning system, not a bill. A big turn is not always bad: large files, cross-agent handoff, long context, or a provider-native coding harness can all be intentional. What matters is the pattern. If one routine triples overnight, or one provider starts carrying unexpected volume, usage rollups give you a place to start looking before it becomes a quota or billing surprise.

What to read next

• Connecting the providers that do the spending -> /operator/providers/
• Defining which agents use which providers -> /operator/agents-config/
• Standing up and maintaining the box -> /operator/provisioning/