再販業者と SaaS テナント向けに顧客対応の AI 使用状況レポート API を構築する
下流顧客が信頼できる AI API 使用状況レポート API を設計するための実践的なガイド: テナント スコープのディメンション、暫定コストと最終コスト、カーソル ページネーション、調整、調整、プライバシーに安全なアクセス制御。
内部ゲートウェイ台帳は、顧客向けのレポート API とは異なります。台帳は、プラットフォーム内で何が起こったかを証明します。顧客レポートでは、テナント、クライアント、ワークスペース、またはエンド カスタマーが請求書発行前に安全に確認、照会、調整、および使用できるものについて説明します。
この区別は、AI の使用を自社の顧客に公開する再販業者、代理店、組み込み AI 製品、SaaS チームにとって重要です。顧客は「いくら使いましたか?」と尋ねるだけではありません。どのキー、モデル、エンドポイント、ワークフロー、ユーザー コホート、または時間バケットが支出の原因となったかを尋ねます。その番号が最終的なものであるかどうか。請求書が昨日のダッシュボードと異なる理由。プロンプトまたはプロバイダーの資格情報がプロセスで公開されるかどうか。
実際的な答えは、不変の使用状況イベント、バージョン管理された価格設定、範囲指定されたアクセス トークン、および調整エンドポイントに裏付けられた、安定した AI API 使用状況レポート API を公開することです。 API は、退屈で、明示的で、誤解されにくいものである必要があります。
データ モデルの前にレポート コントラクトを定義する
ストレージ スキーマではなく、顧客の問題から始めます。レポート API は 4 つの質問に答える必要があります:
- このテナントは何を使用しましたか?
- 顧客に表示される価格設定ルールではいくらかかりましたか?
- その数値は推定値ですか、調整済みですか、それとも最終値ですか?
- 請求書、クレジット、チャージ、パートナー マージンとどのように関係しますか?
これは内部運用ダッシュボードとは異なります。内部システムは、プロバイダー要求 ID、ルーティング決定、生のエラー ペイロード、再試行状態、または資格情報プール名を公開する可能性があります。顧客向けの API では、属性、コストの説明、監査、製品分析に必要なフィールドのみを公開する必要があります。
事実: AI プロバイダーと請求システムは、さまざまなフィールド名、グループ化オプション、集計動作を使用して使用量とコストのデータを公開します。一部の使用状況 API は、モデル、ワークスペース、キー、サービス層などのディメンションごとにグループ化されます。他のサーフェスはエンドポイントのタイプによって異なります。ゲートウェイは、顧客レポートを公開する前にこれを正規化する必要があります。
推奨事項: レポート API を製品契約として扱います。最初のバージョンにエンドポイントがいくつかしかない場合でも、最初のリリースからバージョンを作成します。
テナントスコープのディメンションを使用する
レポート API により、テナントの境界を回避できなくなります。すべてのクエリは、使用状況データにアクセスする前に、承認されたテナント スコープに解決される必要があります。
役立つディメンションは次のとおりです:
customer_id: 下流の顧客またはテナント。project_id: 顧客内のアプリ、環境、チーム、またはワークスペース。api_key_id: ゲートウェイが発行したキー。アップストリーム プロバイダー キーではありません。model_alias: お客様に表示されるモデル名またはプロファイル。provider: オプション。プロバイダーの選択を公開することが契約の一部である場合のみ。endpoint_family: チャット、応答、埋め込み、画像、オーディオ、バッチ、リアルタイム、ツール、または別の安定したカテゴリ。workflow_tag: support-bot、invoice-parser、coding-agent、qa-eval などの顧客指定のタグ。user_hash: デフォルトで個人データを公開しない、帰属を示すための仮名エンドユーザー識別子。time_bucket: 時間単位、日単位、月単位、またはカスタム間隔の境界。
再販業者と代理店の場合、このレポート契約はパートナー プロビジョニング サーフェイスの近くに属します。 パートナー API 自動化 を通じて顧客とキーが作成された場合、使用状況レポートでは 2 番目の命名システムを考案するのではなく、同じ顧客とキーの識別子を使用する必要があります。
使用単位と金額フィールドを個別に公開する
優れたレポートでは、物理的な使用量と価格が区別されます。トークン、ツール呼び出し、画像、音声秒、バッチジョブはお金ではありません。金額は、使用量、価格設定ルール、割引、クレジット、マージン、調整から計算されます。
少なくとも、各集計行には次のようなフィールドが含まれている必要があります:
{
"bucket_start": "2026-09-01T00:00:00Z",
"bucket_end": "2026-09-02T00:00:00Z",
"customer_id": "cus_123",
"project_id": "proj_support",
"api_key_id": "key_789",
"model_alias": "support-fast",
"endpoint_family": "chat",
"request_count": 18420,
"input_tokens": 9821000,
"cached_input_tokens": 2410000,
"output_tokens": 1268000,
"reasoning_tokens": 310000,
"tool_calls": 860,
"estimated_cost": "142.36",
"settled_cost": "141.91",
"currency": "USD",
"pricing_catalog_version": "2026-09-01",
"invoice_status": "pending"
}請求書が金銭建てであるという理由だけでトークン カテゴリを非表示にしないでください。お客様は動作をデバッグするためにユニット フィールドが必要です。キャッシュされた入力トークン、推論トークン、ホストされたツールの料金、およびメディア ユニットによって、2 つの同様のワークフローの費用が異なる理由が説明されることがよくあります。
推奨事項: API 個の応答に小数点以下の通貨を文字列として保存します。コストフィールドには浮動小数点値を使用しないでください。 1 つのグローバル通貨を想定するのではなく、すべての行に通貨フィールドを使用します。
暫定使用量、調整後使用量、最終使用量を個別に分ける
顧客向けの AI レポートは、すべての数値がすぐに最終的なものであるかのように装うため、失敗することがよくあります。実際には、最初のリクエストが完了した後に使用法が変更される可能性があります。
一般的な原因は次のとおりです:
- プロバイダーが最終的な使用状況を返す前にクライアントが切断されるストリーミング応答。
- バッチ、メディア、またはホストされたツールのプロバイダによる遅延使用。
- アプリケーションでは 1 つの論理リクエストが認識されるが、ゲートウェイでは複数の請求可能な試行が認識される再試行。
- 返金、クレジット、価格修正、または不正行為の取り消し。
- 顧客に表示される名前が上流のモデル ID と異なる場合、モデル エイリアスが変更されます。
昨日の API 応答を説明できなくなるような方法で、黙って行を上書きしないでください。代わりに、状態モデルを公開します:
provisional: ゲートウェイの推定値または部分的なプロバイダー データから計算されます。settled: 正規化されたプロバイダの使用状況とアクティブな価格カタログから計算されます。adjusted: 後の修正、クレジット、払い戻し、または調整イベントによって変更されました。invoiced: 顧客が閲覧できる請求書または明細書に含まれます。
生の使用状況イベントは不変である必要があります。修正は、元のイベントまたは集計期間にリンクされた調整行として表示されます。
{
"adjustment_id": "adj_456",
"original_event_id": "evt_abc",
"customer_id": "cus_123",
"reason": "provider_usage_correction",
"cost_delta": "-0.45",
"currency": "USD",
"created_at": "2026-09-03T10:15:00Z"
}トレードオフ: ほぼリアルタイムのレポートは、予算のアラートと顧客の信頼にとって優れていますが、暫定的な状態を目に見える形で表示する必要があります。確定済みのみのレポートは調整が容易ですが、請求書が届く前に顧客が使い過ぎを止めようとしている場合にはあまり役に立ちません。
集計と生のイベントへのアクセスを提供する
1 つのエンドポイントですべてのユースケースに対応できるわけではありません。ダッシュボードには安価な集約が必要です。財務チームや企業顧客は行レベルの証拠を必要とする場合があります。
実際のレポート API には通常、少なくとも 3 つのエンドポイント ファミリがあります:
GET /v1/usage/summary
GET /v1/usage/events
GET /v1/usage/reconciliationサマリーエンドポイント
概要エンドポイントは、ディメンションとタイム バケットの小さなセットごとに事前に集計された使用量を返す必要があります。
GET /v1/usage/summary?customer_id=cus_123&from=2026-09-01T00:00:00Z&to=2026-09-08T00:00:00Z&bucket=day&group_by=model_alias,api_key_idダッシュボード、予算ページ、顧客向けの費用の内訳に使用します。生のイベント テーブルをスキャンせずに繰り返し呼び出すのに十分な速度が必要です。製品に AI API 使用状況分析ダッシュボード が含まれている場合、このエンドポイントは通常、エクスポートされたレポートと UI の一貫性を保つバックエンド コントラクトです。
イベントエンドポイント
イベント エンドポイントは、カーソル ページネーションを使用して不変の使用状況レコードを公開する必要があります。監査を頻繁に行う顧客、調査のサポート、倉庫のエクスポートに使用します。
GET /v1/usage/events?customer_id=cus_123&from=2026-09-01T00:00:00Z&limit=500&cursor=eyJpZCI6...各行には、安定した event_id、タイムスタンプ、リクエスト ファミリ、モデル エイリアス、キー ID、正規化された使用単位、コスト フィールド、ステータスが含まれている必要があります。デフォルトでは、生のプロンプトや補完を含めるべきではありません。
調整エンドポイント
調整エンドポイントは、使用状況を顧客に表示される請求オブジェクトに関連付けます。
GET /v1/usage/reconciliation?customer_id=cus_123&invoice_id=inv_2026_09請求書の品目、使用量合計、適用されたクレジット、チャージ、税金 (該当する場合)、パートナー マージン ルール (顧客が表示できる場合)、および最初の見積もり後に行われた調整を返します。ここでは、使用状況レポートが、カウンタの山ではなく、説明可能な請求書となります。
推奨事項: 請求書と使用状況レポートは関連性を保ちますが、同一ではありません。使用法 API は消費を説明します。請求書には支払い可能な金額が記載されています。これらは、過負荷になった 1 つのエンドポイントに崩壊するのではなく、安定した ID を通じて調整する必要があります。
Cursor ページネーションと安定した順序付けを使用する
オフセット ページネーションは、顧客のページネーション中に新しいレコードや遅延調整が到着する可能性があるため、使用状況イベントに対して脆弱です。安定した並べ替えでカーソルのページネーションを使用します。
耐久性のあるパターンは次のとおりです:
event_timeとevent_idで並べ替えます。- さらにレコードが存在する場合は
next_cursorを返します。 - カーソルを不透明にします。
- 遅れて到着したイベントが既読ウィンドウに表示されるかどうかを文書化します。
- 調整ジョブに
updated_sinceフィルタを提供します。
集約エンドポイントの場合、顧客は反復可能なレポートを必要とする場合があります。 finalized_before または report_version パラメータをサポートすることで、財務エクスポートを一貫して再実行できます。
GET /v1/usage/summary?customer_id=cus_123&month=2026-09&status=finalized&report_version=2026-10-02予測: プロバイダーが新しいトークン タイプ、ツール料金、サービス レベル、メディア請求単位を追加するにつれて、AI 使用量のレポート スキーマは変化し続けます。バージョン管理されたレポート コントラクトは、現在のプロバイダーの応答に含まれているものをすべて公開するエンドポイントよりも古くなります。
バージョンの価格とスキーマの組み合わせ
使用状況フィールドと価格設定ルールは個別に変更されます。モデルには、キャッシュされたトークンの価格が適用される場合があります。プロバイダーは推論トークン制御を導入する場合があります。再販業者は古い契約を尊重しながら、新規顧客のマージン ルールを変更する場合があります。
すべてのコスト行には次の内容を含める必要があります:
pricing_catalog_versionschema_versionrate_effective_atcurrencycost_basis: 見積、決済、調整、請求
これは、プラットフォームが複数のモデル プロバイダーにわたって 統合 AI API 請求 を提供する場合に特に重要です。単一の請求書は、異種の使用量が一貫したコスト カテゴリにどのように正規化されたかを顧客が理解できる場合にのみ役立ちます。
事実: オープンなコストと使用量のスキーマは、AI、クラウド、SaaS、データセンター、その他のテクノロジー ベンダーをカバーするように進化しています。これにより、1 つの永続的なエクスポート形状をハードコーディングするのではなく、バージョン管理されたアプローチがサポートされます。
API
の一部としてアクセス制御を設計する使用状況データは機密です。これにより、顧客の増加、製品の発売、自動化の失敗、不正使用インシデント、または内部ワークフローが明らかになる可能性があります。アクセス制御は後付けではなく、レポート設計の一部である必要があります。
役割を明示的に定義します:
customer_admin: 顧客スコープのすべての使用状況を表示できます。project_admin: 割り当てられたプロジェクトの使用状況を表示できます。billing_viewer: 費用と請求書の調整は表示できますが、ユーザーレベルの内訳は表示できません。support_operator: 監査ログを使用して、サポート ケースの狭いスライスを取得できます。partner_operator: デフォルトではすべてのテナントではなく、割り当てられたテナントを表示できます。
マシン アクセスにはスコープ指定されたトークンを使用します。 cus_123 の使用状況をクエリできるトークンは、ID を推測してキーを変更したり、価格を変更したり、別の顧客の使用状況を読み取ったりすることはできません。
また、どのディメンションがプライバシーに配慮するかを決定します。 user_hash フィールドは、一部の顧客にとっては安全ですが、他の顧客にとっては危険すぎる可能性があります。ワークフロー タグは、顧客がメタデータに買収ターゲットや法的レビューなどの名前を入れた場合、ビジネス コンテキストを漏洩する可能性があります。保存と秘匿化の動作を明確に文書化します。
最小限の実装チェックリスト
このシーケンスを使用すると、完全に見えても調整できないレポート API の作成を回避できます。
- 不変の使用状況イベントを作成します。 すべての課金対象イベントに、安定した ID、テナント スコープ、リクエスト ファミリ、モデル エイリアス、正規化された単位、タイムスタンプ、およびソース ステータスを割り当てます。
- プロバイダーの使用状況を内部単位に正規化します。 必要に応じて生のプロバイダー ペイロードを内部に保持しますが、安定した顧客フィールドは公開します。
- バージョン付きの価格カタログを適用します。 すべての見積もり、決済、調整に使用されるカタログのバージョンを保存します。
- 時間ごとおよび日ごとの集計を具体化します。 ダッシュボード クエリで顧客規模で生のイベントをスキャンしないでください。
- 調整行を追加します。 説明なしに古い費用合計を変更して修正を非表示にしないでください。
- カーソルでページ分割されたイベント エクスポートを構築します。 不透明なカーソル、安定した順序付け、および更新以降のフィルターが含まれます。
- 請求書調整を作成します。 使用量行を請求書品目、クレジット、チャージ、マージン ルールにリンクします。
- テナント スコープの承認を適用します。 すべてのレポート エンドポイントにわたってオブジェクト レベルの承認が壊れていないかテストします。
- スキーマ バージョンを公開します。 クライアントに安定したレポート形式をリクエストする方法を提供します。
- デフォルトでは、生のプロンプト保持はありません。 使用状況レポートには、プロンプトまたは完了の保存は必要ありません。
一般的なトレードオフ
集約ファーストまたはイベントファースト: 集約ファースト API は、ほとんどのお客様にとってより安全で安価です。イベントのエクスポートはより強力ですが、プライバシー、ページネーション、サポートの負担が大きくなります。購入者に監査要件がない限り、最初にオファーの集計を行います。
プロバイダ名を公開するか非表示にする: 上流プロバイダを公開すると、洗練された顧客がパフォーマンスとコストを分析するのに役立ちます。プロバイダーを非表示にすることで、製品の抽象化がより明確になります。ルーティングが価値提案の一部である場合は、プランまたはロールによって制御されるオプションのディメンションとしてプロバイダーを公開することを検討してください。
リアルタイムの見積もりまたは最終レポート: リアルタイムの見積もりは、支出が請求問題になる前に顧客が行動するのに役立ちます。最終レポートは会計に適しています。ほとんどの成熟したシステムには両方が必要です。
厳密な財務スキーマまたは製品に適したスキーマ: 財務指向のスキーマは統合作業を軽減できますが、顧客の製品 API にとっては重すぎる可能性があります。実際的な妥協策は、よりシンプルでバージョン管理された顧客スキーマを公開しながら、財務にインスピレーションを得たフィールドを内部で使用することです。
実用的な結論
顧客向けの AI 使用状況レポート API は、プロバイダーの請求応答や内部管理テーブルの薄いラッパーであってはなりません。これは、プロンプトやアップストリームの認証情報を公開することなく、テナントが請求書発行日前に使用量を把握し、適切なディメンションを掘り下げ、暫定コストと最終コストを区別し、料金を調整できる安定した契約である必要があります。
概要、イベント、調整という 3 つのエンドポイントを中心に最初のバージョンを構築します。不変の使用状況イベント、調整行、バージョン管理された価格設定、カーソルのページネーション、およびテナント スコープのアクセス トークンを使用してそれらをバックアップします。この基盤は、請求書のあらゆる質問を手動のサポート調査に変えることなく、ダッシュボード、顧客の輸出、再販業者の業務、請求に関する紛争をサポートするのに十分です。