Skip to main content
キャンペーン配信後のベンダーサービスの消費状況を報告します。オーケストレーターがベンダーエージェント（シグナル、ガバナンス、クリエイティブ）に使用状況を通知し、ベンダーが獲得収益を追跡して請求を検証できるようにするために呼び出す。 各利用レコードは自己完結型 — 独自の account と media_buy_id を持ちます。単一のリクエストが複数のアカウントとキャンペーンにまたがることができます。 応答時間: 約1秒。 リクエストスキーマ: /schemas/latest/account/report-usage-request.json レスポンススキーマ: /schemas/latest/account/report-usage-response.json

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

パラメーター型必須説明
idempotency_keystring推奨このリクエストのクライアント生成一意キー（UUID 推奨）。同じキーを持つリクエストが既に受け入れられている場合、サーバーは再処理せずに元のレスポンスを返します。再試行時の二重請求を防ぐ。
reporting_periodobjectYesUTC の ISO 8601 日時形式の start と end。リクエスト内のすべてのレコードに適用されます。
usageUsageRecord[]Yes1つ以上の利用レコード。

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

各レコードには account、vendor_cost、currency が必要。追加フィールドはベンダータイプによる。
フィールド型必須説明
accountAccountRefYesこのレコードのアカウント — account_id または { brand, operator } で指定。
vendor_costnumberYesこのレコードでベンダーに支払う金額（currency 単位）
currencystringYesISO 4217 通貨コード
pricing_option_idstringシグナル: Yesget_signals レスポンスの pricing_options から選択した料金オプション。ベンダーはこれを使用して正しいレートが適用されたことを検証します。
impressionsnumberシグナル: Yes配信されたインプレッション数
media_spendnumberpercent_of_media: Yesパーセント・オブ・メディアコスト検証用のメディア支出
signal_agent_segment_idstringシグナル: Yesget_signals からのシグナル識別子

​
レスポンス

フィールド説明
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"
    }
  ]
}

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

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_OPTIONpricing_option_id がこのアカウントに見つからないベンダーの探索レスポンスから pricing_option_id を確認
DUPLICATE_REQUESTこの idempotency_key を持つリクエストが既に受け入れられている無視して安全 — 元のレスポンスが変更なく返される

​
次のステップ