3.2.0-beta.10). Features may change before the next stable release.Switch to stable →usage
ak usage summary
Sum local Claude Code and Codex token usage for the current UTC day, week, or month, by runtime, provider, and model, with an estimated cost.
Use ak usage summary to see how many tokens your Claude Code and Codex
sessions used in the current day, week, or month. The command is read-only and
never opens a network socket.
Usage
ak usage summary [--period day|week|month] [--no-live] [flags]ak usage summary
ak usage summary --period week
ak usage summary --period month --json
ak usage summary --no-liveOptions
| Flag | Default | Description |
|---|---|---|
--period <name> | day | day, week, or month: the current UTC calendar period. |
--no-live | false | Do not parse session transcripts when the analytics index cannot answer. |
Shared flags are described in CLI conventions.
What it counts
The summary covers every Claude Code and Codex session that started in the current UTC calendar period, from the period start up to now. A week starts on Monday.
- Token lanes. Input, output, cache write, and cache read, plus their total. Token counts are exact.
- Breakdowns. Totals are also grouped by runtime, by provider, and by model.
- Reasoning. Reasoning tokens are counted inside output. A separate reasoning lane is always reported as unavailable, never as zero.
- Cost. An estimate at the public API rates built into this release of
ak. When any model in the period has no known rate, the cost is unavailable as a whole rather than partial. - Provider windows. Subscription windows are always unavailable here. Use
ak usage limitsfor rolling windows and opt-in provider-reported quotas.
Where the numbers come from
The local analytics index answers first. Its results include the time that
index generation was published; sessions that started after it appear after
the next ak analytics refresh.
When the index is absent or not ready, the command parses the session
transcripts for the period directly and reports source live. It prints a
notice on stderr first, because a long history can take a while to scan. With
--no-live it skips that scan and reports no usage data, with a hint to run
ak analytics enable or ak analytics refresh, or to rerun without
--no-live.
The index is opened read-only under ~/.agentkit/analytics/
(AGENTKIT_HOME overrides the base directory). The command never writes,
refreshes, or creates it.
Output
The text output prints the period and its UTC bounds, the session count and
source, a token table for all sessions and for each runtime, provider, and
model, the cost, and a reminder that provider windows come from
ak usage limits.
JSON uses kind=usage.summary with these fields under data:
schema_version, period, period_start, period_end, source, index_state,
indexed_at, sessions, tokens, by_runtime[], by_provider[], by_model[], cost,
usage_windows[], local_only
tokens: input, output, cache_creation, cache_read, total, quality, reasoning
by_*[]: key, runtime?, sessions, tokens
cost: quality, amount_usd, basis?, as_of[], reason?sourceisindex,live, orunavailable.index_stateisready,absent, ornot_ready.indexed_atis empty unlesssourceisindex.cost.qualityisestimatedwith anamount_usd, orunavailablewith areasonsuch asno_data,pricing_unavailable,unpriced_runtime, orunpriced_model.- Each
usage_windowsentry isunavailablewith the reasonprovider_window_not_local. local_onlyis alwaystrue.
Exit behavior
| Exit | Meaning |
|---|---|
0 | Success, including a period with no usage data. |
1 | Command failure, such as an index or transcript read error. |
2 | Invalid flags or arguments, such as an unknown --period. |