Codex session usage
Documentation / Agent integrations / Codex
Import a local Codex rollout to estimate its API-equivalent usage. This is not a subscription invoice or proof of the amount a provider charged.
Read an explicit file#
trazum from-codex ./rollout.jsonl --label coding -o usage.jsonl
trazum bill ./rollout.jsonl --table
trazum profile usage.jsonl
trazum plan usage.jsonl -o plan.json
trazum verify plan.json --against newer-usage.jsonlfrom-codex accepts a file or directory. Directory reads recurse through
.jsonl and .ndjson files; from-codex never looks in your Codex home by
itself. Since 2.7.0, trazum bill with no path does: it reads
$CODEX_HOME/sessions and $CODEX_HOME/archived_sessions (~/.codex when
CODEX_HOME is unset, the folders Codex's own source names), names each
folder on stderr before reading it, and splits the statement by agent when
Claude Code or Gemini CLI sessions were read too.
Decompress archives before importing them. Without -o, normalized JSONL goes
to stdout; diagnostics go to stderr. Conversion with no attributable records
fails instead of writing an empty output.
bill detects this format in explicitly supplied inputs. The browser Bill
also accepts uploaded rollout files and converts them locally. For MCP
workflows, call import_usage with format: "codex", rollout text and an
optional explicit label. Pass its normalized log to the usage tools
and preserve the import diagnostics alongside their reports. CLI conversion
remains available; neither route establishes source completeness. The
HTTP /usage/import also accepts format: "codex"
and transcript text, with an optional explicit label of at most 200 characters.
It is available since 2.6.0. Both its request and complete JSON response
are capped at 1,000,000 UTF-8 bytes; overflow returns 400. Do not blindly split
and recombine snapshots to fit: counter/model context and per-request
deduplication affect the result. Preserve diagnostics even when the normalized
log is empty; empty does not mean free usage. The HTTP savings endpoints consume
the normalized log, with log and plan sharing the verification request cap.
Raw conversation text is not required by savings analysis.
What is counted#
The converter reads session_meta, model-bearing turn_context, and
event_msg / token_count telemetry. A usage snapshot is retained only when
its cumulative delta matches its last-call counts. Identical cumulative
snapshots are duplicates, including repeated rate-limit updates. Per-session
high-water counters survive rewinds and session switches within a file. A
rewind cannot establish a new billable origin: only a corroborated progression
beyond the previous high-water mark can contribute new usage.
Cached input is subtracted from ordinary input and retained separately. Reasoning output is already inside output tokens and is not added twice. Models retain their recorded names. Unknown models stay unpriced; no model alias or price is guessed. The timestamp is retained only when valid.
Only model, timestamp, session ID, optional caller-supplied label and token counts survive conversion. Prompts, responses, instructions, working paths and other session metadata are discarded. Output still contains session IDs and labels; review those before sharing it.
What cannot be established#
- Restored totals and aggregate jumps do not establish individual calls or their historical models. They establish a baseline for later deltas only.
- Missing model context, invalid counters, counter resets, synthetic context-window fills and nonzero cache-write counters are excluded.
- A partial file may lack earlier context. Repeated copies of the same rollout supplied as separate files are not deduplicated across files.
- Codex telemetry can be estimated, replayed or incomplete. Even a fully converted file does not prove complete provider billing or subscription use.
Conversion reports duplicate and excluded counts separately. bill JSON adds
importEvidence for Codex inputs: source, basis, files, duplicates,
missingModel, unsupported, unparseable and complete. complete means no
conversion exclusions were observed, not that billing is complete. Receipt
gaps still records unpriced models and other profile gaps. Consumers that
retain only the standard receipt fields must retain import evidence separately.
Normalized JSONL cannot carry excluded snapshots: preserve conversion stderr
alongside that file when auditing or planning savings.
Upstream format evidence#
Implementation was checked against OpenAI Codex commit
97239fd052db455bd08c41afcdab738e0fe83b87:
protocol counters and rollout context
and Responses usage mapping.
The protocol distinguishes token-count telemetry from exact raw response
completion usage. Future upstream changes may require an adapter update;
unsupported shapes are excluded rather than interpreted as zero-cost calls.