Events Export

llm-usage events streams the normalized usage events every report is built from: one record per usage record the source logged, after source parsing, normalization, and pricing. It is the raw-data counterpart to the aggregated reports.

Command structure

llm-usage events [options]

Examples:

llm-usage events > events.jsonl
llm-usage events --format csv --since 2026-01-01 > events.csv
llm-usage events --source codex --since 2026-06-01 | jq '.totalTokens'

Options

• --format <name>: jsonl (default), csv, otlp-traces, or otlp-metrics (OpenTelemetry export)
• --otel-include-paths: with otlp-traces, add repository paths to the spans
• --otlp-endpoint <url>: with otlp-traces or otlp-metrics, POST the export to an OTLP/HTTP receiver instead of printing it (Push to a receiver)
• shared filters apply: --source, --provider, --model, --repo, --machine, --since, --until, --timezone, source-path overrides, pricing flags, --cost-mode, and --no-history

events is an export stream, not a report: it takes --format instead of --json, and has no --markdown or --share. Diagnostics go to stderr as usual, so redirecting stdout produces a clean data file.

Export contract

• jsonl (default): one JSON object per line with the exact UsageEvent field names; absent optionals (repoRoot, provider, model, singleRequest, costUsd, machine) are omitted, not null. singleRequest is true when the event records exactly one model request, the events long-context tiers apply to; the CSV has no column for it. machine names the machine an event came from; this machine’s own events have none. Lines are not wrapped in the report envelope. Each line validates against events-line.v1.schema.json.
• csv: a frozen header row with all 16 columns (source,sessionId,timestamp,repoRoot,provider,model,inputTokens,outputTokens,reasoningTokens,cacheReadTokens,cacheWriteTokens,totalTokens,costUsd,costMode,machine,cacheWrite1hTokens; machine was appended in the multi-machine release, then cacheWrite1hTokens, the part of cacheWriteTokens cached for one hour), RFC 4180 quoting, empty string for absent optionals. New fields will only ever be appended as trailing columns. Cells that begin with a spreadsheet formula trigger (=, +, -, @, tab, carriage return) are prefixed with a single apostrophe to prevent formula execution, per OWASP CSV-injection guidance; use --format jsonl when you need raw values.
• Ordering is deterministic: timestamp, then source, then sessionId, then original parse order.

{
  "source": "codex",
  "sessionId": "486c3261-d87e-4971-8813-904c9e5a9009",
  "timestamp": "2026-06-15T12:00:00.000Z",
  "repoRoot": "/path/to/repo",
  "provider": "openai",
  "model": "gpt-5.2-codex",
  "inputTokens": 150,
  "outputTokens": 100,
  "reasoningTokens": 20,
  "cacheReadTokens": 50,
  "cacheWriteTokens": 0,
  "cacheWrite1hTokens": 0,
  "totalTokens": 300,
  "singleRequest": true,
  "costUsd": 0.0017,
  "costMode": "estimated"
}

OpenTelemetry

--format otlp-traces exports sessions as OTLP/JSON traces instead of usage lines, and --format otlp-metrics exports daily token, cost and tool duration metrics. OpenTelemetry export describes the span tree, the metrics, the attribute mapping onto the GenAI conventions, and a Collector config that replays the file into a backend.