AdCP — report

キャンペーン配信後のベンダーサービスの消費状況を報告します。オーケストレーターがベンダーエージェント（シグナル、ガバナンス、クリエイティブ）に使用状況を通知し、ベンダーが獲得収益を追跡して請求を検証できるようにするために呼び出す。各利用レコードは自己完結型 — 独自の account と media_buy_id を持ちます。単一のリクエストが複数のアカウントとキャンペーンにまたがることができます。 応答時間: 約1秒。 リクエストスキーマ: /schemas/v3/account/report-usage-request.json レスポンススキーマ: /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	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`	個々のレコードのバリデーションエラー。部分的な受け入れは有効 — 一部が失敗しても受け入れられたレコードは保存されます。

例

シグナル利用 — 単一キャンペーン

{
  "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"
    }
  ]
}

{
  "accepted": 1
}

クリエイティブ利用 — CPM 課金のアドサーバー

{
  "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"
    }
  ]
}

{
  "accepted": 1
}

マルチアカウントバッチ

2つのアカウントにまたがる2つのキャンペーンの単一リクエスト:

{
  "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"
    }
  ]
}

部分的な受け入れ

一部のレコードがバリデーションに失敗した場合、レスポンスは受け入れられた数を示します:

{
  "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 — 報告前にセラーと広告主アカウントを同期します
アカウントプロトコル — アカウント確立と精算の全体像
アカウントとエージェント — 請求階層とオペレーターモデル

はじめに

AdCP で構築する

プロトコル

FAQ

トラストとセキュリティ

リファレンス

AAO

認定

report_usage

リクエストパラメーター

利用レコードのフィールド

レスポンス

例

シグナル利用 — 単一キャンペーン

クリエイティブ利用 — CPM 課金のアドサーバー

マルチアカウントバッチ

部分的な受け入れ

再試行の安全性

報告ケイデンス

エラーハンドリング

次のステップ

​リクエストパラメーター

​利用レコードのフィールド

​レスポンス

​例

​シグナル利用 — 単一キャンペーン

​クリエイティブ利用 — CPM 課金のアドサーバー

​マルチアカウントバッチ

​部分的な受け入れ

​再試行の安全性

​報告ケイデンス

​エラーハンドリング

​次のステップ

リクエストパラメーター

利用レコードのフィールド

レスポンス

例

シグナル利用 — 単一キャンペーン

クリエイティブ利用 — CPM 課金のアドサーバー

マルチアカウントバッチ

部分的な受け入れ

再試行の安全性

報告ケイデンス

エラーハンドリング

次のステップ