使用量統計 API

ChatWalaʻau は消費したトークンを追記専用の台帳に記録しています。 GET /api/usage/summary で読み出し、GET /api/usage/export で CSV としてダウンロードできます。アプリ内ではトークン使用量ダッシュボードで同じ数値を確認できます。

記録されるもの

モデルを呼び出すすべてのレーンのターンが対象です。

Web アプリのチャット（通常のチャットと Harness エージェントの両方）
宣言的ワークフローの実行 -- 実行されたノードごとに 1 行。チャットからの実行と Pipeline ジョブの両方（v0.154.0 以降）
Microsoft Teams の会話
OpenAI 互換 API 経由のリクエスト
表に出ないバックグラウンド処理: チャットタイトル生成、ユーザー記憶の抽出、エージェント記憶のキュレーション、オントロジーの自然言語クエリ、Teams 会議要約

中断したターンも記録されます。 その時点までに消費した分を記録します。回答を受け取ったかどうかに関わらず、トークンは課金されているためです。

ワークフローの実行はノード単位

ワークフローは 1 回の実行につき 1 行ではありません。エージェントを呼び出したノードがそれぞれ 1 行を書くため、ワークフローのどのステップが高コストかを確認できます。

{ "lane": "workflow", "kind": "node", "run_target": "Contract Review Flow",
  "node": "summarize_step", "agent": "Summarizer", "run_id": "b41e...",
  "model_calls": 3, "uncached_input_token_count": 2100, "output_token_count": 480 }

run_target はワークフローの名前、node は YAML に書いたステップの id、agent はそのステップが呼び出した Prompt エージェントです。
ループ内のノードは、実行されるたびに 1 行を書きます。
run_id は 1 回の実行に属する行をまとめます。途中で質問のために一時停止し、回答を受けて再開した実行も同じ run_id になります。
Pipeline ジョブ として実行したワークフローは lane: "workflow-job" で、チャットはなく、run_id はジョブ ID です。
ワークフローの最初の応答の後に生成されるチャットタイトルは、run_target にワークフロー名を持つタイトル生成の行として記録されます。

チャット画面では、ワークフローの応答の in/out ラベルに 実行全体の合計 が表示されます。クリックすると、ノード別の内訳と、モデルのウィンドウ上限に最も近づいたノードのコンテキスト占有率を確認できます。

記録されないもの

デモモード。 トークン数が実測ではなく推定値のため、記録すると実統計に作り物の数値が混入します。
プロバイダが使用量を報告する前に失敗したモデル呼び出し。 どのレーンでも、記録できる数値が存在しません。

v0.154.0 で追加

以前のバージョンでは、宣言的ワークフローの実行を「計装はまだ行っていない」としてここに挙げていました。現在はノード単位で記録されます。

v0.145.1 で訂正

以前のこのページ、および coverage フィールド自体が、フレームワーク内部のコンテキスト圧縮呼び出しを「未記録の消費」として挙げていました。これは誤りです。本アプリの圧縮はトークン予算に従って履歴を切り詰めるだけで、モデルを呼びません。したがって記録すべき消費は発生しません。要約型の圧縮戦略であれば消費しますが、それは構成されていません。ギャップを過大に申告することは、正確だった数値を信用しないよう促すことになります。

すべてのレスポンスの coverage フィールドにこの旨が入ります。ここに出る合計は「観測可能な作業が消費した量」であり、「アカウントに請求された金額」ではありません。

保存場所

# .env
USAGE_DIR=.usage    # 既定値

1 か月 1 ファイル、1 ターン 1 行の JSON です。

.usage/2026-09.jsonl

チャットとは別ディレクトリにしているのは意図的です。チャットの削除、一時チャットの自動削除、チャットのエクスポート/インポートはいずれもセッションディレクトリを操作するため、消費記録はその 3 つすべてを生き延びる必要があります。

台帳から何かが削除されることはなく、保持期間の設定もありません。

読み出し

curl -s -H "Authorization: Bearer $API_KEY" \
  "http://localhost:8000/api/usage/summary?from=2026-09-01&to=2026-09-30&group_by=day"

パラメータ	値	既定
`from` / `to`	`YYYY-MM-DD`（両端含む、`tz` の日付）	直近 30 日
`tz`	IANA タイムゾーン（例: `Asia/Tokyo`）	`UTC`
`group_by`	`day`, `month`, `chat`, `model`, `lane`, `run_target`, `node`, `agent`, `provider`, `outcome`, `kind`	`day`
`series`	同じ一覧から選ぶ 2 つ目のグルーピングキー（`group_by` と別のもの）	なし
`lane`	`spa-prompt`, `spa-harness`, `workflow`, `workflow-job`, `teams`, `openai-api`, `helper`	すべて

group_by=node は各グループのキーを "<ワークフロー名> / <ノード ID>" とします。同じステップ ID が別のワークフローにも現れうるためです。group_by=run_target はワークフロー（および Harness エージェント）を名前でまとめます。

自分のタイムゾーンの日付で集計（v0.157.0）

台帳は UTC で保存されます。tz を指定すると、from・to と day / month のキーがそのタイムゾーンの日付になります。たとえば 2026-08-31T20:00Z に書かれたレコードは、tz=Asia/Tokyo では 2026-09-01 に数えられます。tz を省略すると従来どおりすべて UTC です。

2 軸での集計（v0.157.0）

series は各グループをさらに分割します。group_by=day&series=model では、日ごとにモデル別の series 行が付き、その合計は必ずその日の値と一致します。すべてのグループ・行・totals には、最初と最後の利用時刻 first_ts / last_ts も付きます。

{
  "from": "2026-09-01",
  "to": "2026-09-30",
  "tz": "UTC",
  "group_by": "day",
  "groups": [
    {
      "key": "2026-09-04",
      "records": 128,
      "model_calls": 402,
      "uncached_input_token_count": 51200,
      "cache_read_input_token_count": 230400,
      "output_token_count": 15360,
      "reasoning_output_token_count": 6400
    }
  ],
  "totals": { "records": 128, "model_calls": 402 },
  "skipped_lines": 0,
  "coverage": "Observable model calls only. ..."
}

BI 向けのエクスポート（v0.157.0）

curl -s -H "Authorization: Bearer $API_KEY" -o usage.csv \
  "http://localhost:8000/api/usage/export?from=2026-09-01&to=2026-09-30&tz=Asia/Tokyo"

エクスポートは台帳の 生レコード（1 行 = 台帳の 1 行）です。BI ツール側で自由にピボットできます。パラメータは上記の from・to・tz・lane と、format=csv （唯一の形式）です。

ts, ts_local, lane, kind, purpose, thread_id, temporary, model, provider,
run_target, node, agent, run_id, model_calls,
uncached_input_token_count, cache_read_input_token_count,
cache_creation_input_token_count, output_token_count,
reasoning_output_token_count, outcome

ts は保存された UTC 時刻、ts_local は同じ時刻を tz で表したものです。
プロバイダが報告しなかった値は 0 ではなく空欄です。
列の順序は固定です。新しい列は必ず 末尾に追加 されるため、今作った取り込み設定はアップグレード後もそのまま使えます。
BOM 付き UTF-8 のため、Excel でも日本語のワークフロー名・エージェント名が文字化けしません。
表計算ソフトが数式として実行しうる文字列（=、+、-、@ で始まるもの）には先頭に ' が付きます。
X-Usage-Skipped-Lines ヘッダーは読めなかった台帳の行数、X-Usage-Coverage はカバレッジの注記です。
金額の列はありません。

数値の読み方

model_calls は通常ターン数より大きくなります。 ツールを使うターンはステップごとにモデルを呼び、その 1 回ごとに課金されるためです。

入力は価格帯ごとに分けたまま保持します。 キャッシュ読み出しとキャッシュ書き込みは通常の入力と単価が異なり、一度合算すると二度と分離できません。そのため uncached_input_token_count / cache_read_input_token_count / cache_creation_input_token_count は別々のままです。キャッシュ読み出しの比率が高いほど、プロンプトキャッシュが効いています。

表示されないフィールドは「報告されなかった」ものです。 プロバイダがキャッシュ値を報告しない場合、0 ではなくフィールド自体が存在しません。「使っていない」と「測定されていない」を区別できます。

推論トークンは出力の内数です。 reasoning_output_token_count はすでに output_token_count に含まれています。両者を足さないでください。

金額は含みません。 単価は本システムの外で変動し、契約内容にも依存するため、保存すると静かに陳腐化します。ご自身の単価を掛けてください。

名前を残さないチャット

一時チャットは日次・月次の合計には現れますが、チャット別の表示では (temporary) にまとめられます。消えることを前提とした会話であり、消費を帰属させるチャットが存在しないためです。合計は変わらず一致します。

記録されるもの​

ワークフローの実行はノード単位​

記録されないもの​

保存場所​

読み出し​

自分のタイムゾーンの日付で集計（v0.157.0）​

2 軸での集計（v0.157.0）​

BI 向けのエクスポート（v0.157.0）​

数値の読み方​

名前を残さないチャット​