> ## Documentation Index
> Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt
> Use this file to discover all available pages before exploring further.
# report_usage
> report_usage はキャンペーン配信後に消費データを AdCP ベンダーエージェントに送信する — 配信されたインプレッション、照会されたシグナル、実行されたガバナンスチェック — ベンダーが収益を追跡し請求を検証できるよう。
キャンペーン配信後のベンダーサービスの消費状況を報告します。オーケストレーターがベンダーエージェント（シグナル、ガバナンス、クリエイティブ）に使用状況を通知し、ベンダーが獲得収益を追跡して請求を検証できるようにするために呼び出す。
各利用レコードは自己完結型 — 独自の `account` と `media_buy_id` を持ちます。単一のリクエストが複数のアカウントとキャンペーンにまたがることができます。
**応答時間**: 約1秒。
**リクエストスキーマ**: [`/schemas/v3/account/report-usage-request.json`](https://adcontextprotocol.org/schemas/v3/account/report-usage-request.json)
**レスポンススキーマ**: [`/schemas/v3/account/report-usage-response.json`](https://adcontextprotocol.org/schemas/v3/account/report-usage-response.json)
## リクエストパラメーター
| パラメーター | 型 | 必須 | 説明 |
| ------------------ | -------------- | --- | ---------------------------------------------------------------------------------------------- |
| `idempotency_key` | string | 推奨 | このリクエストのクライアント生成一意キー（UUID 推奨）。同じキーを持つリクエストが既に受け入れられている場合、サーバーは再処理せずに元のレスポンスを返します。再試行時の二重請求を防ぐ。 |
| `reporting_period` | object | Yes | UTC の ISO 8601 日時形式の `start` と `end`。リクエスト内のすべてのレコードに適用されます。 |
| `usage` | UsageRecord\[] | Yes | 1つ以上の利用レコード。 |
### 利用レコードのフィールド
各レコードには `account`、`vendor_cost`、`currency` が必要。追加フィールドはベンダータイプによる。
| フィールド | 型 | 必須 | 説明 |
| ------------------------- | ------------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account` | [AccountRef](/docs/building/by-layer/L2/accounts-and-agents#account-references) | Yes | このレコードのアカウント — `account_id` または `{ brand, operator }` で指定。 |
| `vendor_cost` | number | Yes | このレコードでベンダーに支払う金額（`currency` 単位） |
| `currency` | string | Yes | ISO 4217 通貨コード |
| `pricing_option_id` | string | ベンダー: Yes | ベンダーのディスカバリーレスポンス（`get_signals`、`list_creatives`、`list_content_standards`、`list_property_lists`）または実行レスポンス（`build_creative`）からの料金オプション。ベンダーはこれを使用して正しいレートが適用されたことを検証します。 |
| `impressions` | number | シグナル: Yes | 配信されたインプレッション数 |
| `media_spend` | number | percent\_of\_media: Yes | パーセント・オブ・メディアコスト検証用のメディア支出 |
| `signal_agent_segment_id` | string | シグナル: Yes | `get_signals` からのシグナル識別子 |
| `creative_id` | string | クリエイティブ: Yes | `build_creative` または `list_creatives` からのクリエイティブ識別子。請求検証のため利用を特定のクリエイティブにリンクします。`build_creative` のバリアントリーフは、トラフィックされた/ライブラリに追加されたときのみ `creative_id` を得ます — 破棄された best-of-N やファンアウトバリアントはここで報告されません。それらの課金は `build_creative` レスポンス上のインラインのリーフごと `vendor_cost` です（トラフィックされないリーフの権威的レコード）。 |
| `build_variant_id` | string | No | 報告される `creative_id` が特定の `build_creative` バリアントリーフから昇格したがそのソース ID と異なる場合、リコンシリエーションのためソースの `build_variant_id` を運びます。`creative_id` が保持された `build_variant_id` である正準パスでは、このフィールドを省略します。 |
| `property_list_id` | string | プロパティリスト: Yes | `list_property_lists` からのプロパティリスト識別子。請求検証のため利用を特定のプロパティリストにリンクします。 |
## レスポンス
| フィールド | 説明 |
| ---------- | ------------------------------------------------------------ |
| `accepted` | 正常に保存された利用レコード数 |
| `errors` | 個々のレコードのバリデーションエラー。部分的な受け入れは有効 — 一部が失敗しても受け入れられたレコードは保存されます。 |
## 例
### シグナル利用 — 単一キャンペーン
```json リクエスト theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
"reporting_period": {
"start": "2025-03-01T00:00:00Z",
"end": "2025-03-31T23:59:59Z"
},
"usage": [
{
"account": { "account_id": "acct_pinnacle_signals" },
"signal_agent_segment_id": "luxury_auto_intenders",
"pricing_option_id": "po_lux_auto_cpm",
"impressions": 4200000,
"media_spend": 21000.00,
"vendor_cost": 2100.00,
"currency": "USD"
}
]
}
```
```json レスポンス theme={null}
{
"accepted": 1
}
```
### クリエイティブ利用 — CPM 課金のアドサーバー
```json リクエスト theme={null}
{
"idempotency_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"reporting_period": {
"start": "2026-03-01T00:00:00Z",
"end": "2026-03-31T23:59:59Z"
},
"usage": [
{
"account": { "account_id": "acct_acme_creative" },
"creative_id": "cr_88201",
"pricing_option_id": "po_video_cpm",
"impressions": 2400000,
"vendor_cost": 1200.00,
"currency": "USD"
}
]
}
```
```json レスポンス theme={null}
{
"accepted": 1
}
```
### マルチアカウントバッチ
2つのアカウントにまたがる2つのキャンペーンの単一リクエスト:
```json theme={null}
{
"idempotency_key": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"reporting_period": {
"start": "2025-03-01T00:00:00Z",
"end": "2025-03-31T23:59:59Z"
},
"usage": [
{
"account": { "account_id": "acct_pinnacle_signals" },
"signal_agent_segment_id": "luxury_auto_intenders",
"pricing_option_id": "po_lux_auto_cpm",
"impressions": 2100000,
"vendor_cost": 1050.00,
"currency": "USD"
},
{
"account": { "account_id": "acct_nova" },
"signal_agent_segment_id": "eco_conscious_shoppers",
"pricing_option_id": "po_eco_cpm",
"impressions": 800000,
"vendor_cost": 400.00,
"currency": "USD"
}
]
}
```
### 部分的な受け入れ
一部のレコードがバリデーションに失敗した場合、レスポンスは受け入れられた数を示します:
```json theme={null}
{
"accepted": 1,
"errors": [
{
"code": "INVALID_PRICING_OPTION",
"message": "pricing_option_id 'po_unknown' does not exist on this account",
"field": "usage[1].pricing_option_id"
}
]
}
```
## 再試行の安全性
本番利用では必ず `idempotency_key` を含めます。リクエストがタイムアウトまたはネットワークエラーを返した場合、同じキーで再試行する — サーバーは二重計上せずに元の結果を返します。
リクエストごとに新しい UUID を生成する（利用レコードごとではない）。同じ期間に追加レコードを報告する必要がある場合は、新しいキーで新しいリクエストを送信します。
## 報告ケイデンス
定期的に報告する — 最低でも月次。支出が大きいキャンペーンには週次報告により、ベンダーエージェントに獲得収益のタイムリーな可視性を提供します。
最終期間をクローズするため、キャンペーン完了時に報告します。
## エラーハンドリング
| エラーコード | 説明 | 解決策 |
| ------------------------ | ----------------------------------------- | ------------------------------------------------ |
| `ACCOUNT_NOT_FOUND` | 利用レコードのアカウント参照が見つからないか、アクセスできない | `list_accounts` で確認; 必要に応じて `sync_accounts` を再実行 |
| `INVALID_USAGE_DATA` | 利用レコードに欠落または無効なフィールドがある | ベンダータイプの必須フィールドを確認 |
| `INVALID_PRICING_OPTION` | `pricing_option_id` がこのアカウントに見つからない | ベンダーの探索レスポンスから `pricing_option_id` を確認 |
| `DUPLICATE_REQUEST` | この `idempotency_key` を持つリクエストが既に受け入れられている | 無視して安全 — 元のレスポンスが変更なく返される |
## 次のステップ
* [sync\_accounts](/docs/accounts/tasks/sync_accounts) — 報告前にセラーと広告主アカウントを同期します
* [アカウントプロトコル](/docs/accounts/overview) — アカウント確立と精算の全体像
* [アカウントとエージェント](/docs/building/by-layer/L2/accounts-and-agents) — 請求階層とオペレーターモデル