スコープ
get_media_buy_delivery は、基盤となるキャンペーンがどう作成されたかに関わらず、get_media_buys が返す任意の media_buy_id で動作します。セラーエージェントは、購入が AdCP の外で発生したことを理由に、配信レポートを拒否したり、そのカバレッジを狭めたりしてはなりません(MUST NOT)。ある購入の配信データが本当に利用できない場合(例: アドサーバーがまだフライトを報告していない)、セラーはその購入をゼロまたは部分的なメトリクスとともに media_buy_deliveries で返します。セラーはそれを省略せず、アカウントが所有する購入に対して MEDIA_BUY_NOT_FOUND を返しません。
リクエストスキーマ: /schemas/v3/media-buy/get-media-buy-delivery-request.json
レスポンススキーマ: /schemas/v3/media-buy/get-media-buy-delivery-response.json
リクエストパラメーター
日付範囲の挙動: 日付範囲は開始を含み、終了を含みません。例えば日付範囲の例:start_date: "2026-01-01"、end_date: "2026-01-02"は 1 月 1 日のみ(2026-01-01 00:00:00から2026-01-02 00:00:00の直前まで)の配信データを返します。1 週間分(1/1〜1/7)を得るにはend_date: "2026-01-08"を使います。
*
media_buy_ids は結果を特定のメディアバイに絞り込みます。いずれも指定しない場合、現在のセッションコンテキスト内のすべてのメディアバイを返します。
レスポンス
集計とメディアバイごとの内訳を含む配信レポートを返します。Media Buy Delivery オブジェクト
3.1 の語彙に関する注記。
get_media_buy_delivery はライフサイクル状態をネストした media_buy_deliveries[].status フィールドで返します(深さ 1 にネストされているためエンベロープとの衝突なし)。create_media_buy と update_media_buy の成功レスポンスは、同じライフサイクル状態をトップレベルの media_buy_status フィールドで返します(エンベロープのタスクステータス status との衝突を避けるため 3.1 で追加)。同じ列挙で、3.1 では二つのフィールド名——このカスケードは 4.0 で統一されます(#4905)。全体像は移行 › media_buy_statusを参照してください。
完全なフィールド一覧はスキーマを参照してください。
最終値と暫定値
配信行は、その計測ウィンドウについて最終であるか、そうでないかのいずれかです。最終とは、セラーがその期間についてこれらの数値を確定——これ以上の改訂なし——とみなし、購入が作成された際のmeasurement_terms.billing_measurement に従って請求する意思があることを意味します。それ以外はすべて暫定です: 計測が成熟するにつれてまだ落ち着いていく途中であり(放送の C3 → C7 の DVR 累積、IVT 除去後、コンバージョンの重複排除)、請求の信頼できる情報源ではありません。
行ごとのシグナル:
media_buy_deliveries[*].is_finalとmedia_buy_deliveries[*].finalized_at— 行レベルの最終性。行内のすべてのパッケージが同じ計測ウィンドウについて最終である場合にのみ true。media_buy_deliveries[*].by_package[*].is_finalと.finalized_at— 正確なタイムスタンプを伴うパッケージレベルの最終性。media_buy_deliveries[*].by_package[*].measurement_window— 数値がどの成熟ステージを表すか(c3、c7、post_sivt、downloads_30d、…)。
is_final が false(または不在)の行をペーシングやレポートに使う呼び出し元は安全です。照合、未払計上、財務クローズに使う呼び出し元は安全ではありません。
請求について誰が権威的か
どの数値が購入を請求するかは契約条件であり、購入のmeasurement_terms.billing_measurement で宣言されます:
- セラー証明(
billing_measurementが不在、またはセラー自身のアドサーバーを指名する場合の既定):get_media_buy_deliveryの最終行に基づいて請求します。 - ベンダー証明(購入で指名された第三者計測ベンダー——例: Nielsen、IAS、DV、MOAT): 指名されたベンダーの権威ある数値に基づいて請求します。運用上は、セラーがベンダーから取得して
is_final: trueを伴ってget_media_buy_deliveryで公開するのが最も一般的です。バイヤーがベンダーとの関係を保持する場合は、バイヤーがfinal: trueとfinalized_atを設定してreport_usageでプッシュします。 - バイヤー証明(購入で指名されたバイヤーの 3PAS や MMP——例: CM360、Flashtalking):
report_usageでプッシュされたバイヤーの最終記録に基づいて請求します。
measurement_terms.billing_measurement.finalization_deadline_hours 以内に最終値を公開しない場合、相手方は自身の証明にフォールバックしてよい(MAY)。この違反は makegood_policy の下で扱われます。この期限は vendor に指名されたどちらの当事者にも対称的に適用されます。当事者間の差異が max_variance_percent を超える場合、当事者は購入の makegood_policy.available_remedies と帯域外の交渉で解決します。
エンドツーエンドのフローは請求の権威を参照してください。構造化された紛争タスク——ワイヤー上で配信の紛争を開始・遷移・解決する——は AdCP 3.2 を目標としています。
集計メトリクスのパーティション(metric_aggregates)
qualifier(計測標準、透明性の開示)によって変わる購入横断の配信値は、フラットなスカラーではなく aggregated_totals.metric_aggregates のパーティション化された配列として報告されます。これは集計レイヤーでの「リンゴとオレンジの合計」問題を解決します: MRC と GroupM のビューアビリティは実質的に異なる閾値を定義しており、単一のレートに合算してはなりません。
各行は package.committed_metrics と by_package[].missing_metrics と同じ原子単位を運びます:
(scope, metric_id, qualifier) による行レベルの結合です。 各 committed_metrics 行について、一致する metric_aggregates 行を見つけます。一致しないものは missing_metrics として現れます。メトリクスごとの照合ロジックも、契約と配信の間のトラバーサルの非対称性も不要です。
粒度のルール。 (metric_id, qualifier セット全体) ごとに 1 行で、利用可能な最も細かい粒度で報告します。より粗いビューが欲しいバイヤーは再集計します。これによりロールアップの曖昧さがなくなり、偶発的な二重計上を防げます。
qualifier のないメトリクスはトップレベルのまま。 impressions、spend、media_buy_count、その他 qualifier を持たないメトリクスは aggregated_totals のトップに残ります。metric_aggregates は qualifier セットが空でないメトリクスにのみ使われます。
相互排他(MUST)。 metric_aggregates に現れる任意の metric_id について、aggregated_totals の対応するトップレベルのスカラーは省略されなければなりません——ゼロにするのではありません。セラーは両方を出してはなりません(MUST NOT)。信頼できる情報源の重複を避けます。
qualifier の語彙は、今日 committed_metrics と metric_aggregates の両方で閉じています(additionalProperties: false)。五つのキーが存在します: viewability_standard(MRC vs GroupM のビューアビリティ)、completion_source(セラー証明 vs ベンダー証明の完了)、attribution_methodology(deterministic_purchase / probabilistic / panel_based / modeled——成果メトリクス向け)、attribution_window(構造化された期間——成果メトリクス向け)、lift_dimension(awareness / consideration / favorability / purchase_intent / ad_recall——brand_lift 向け)。配信の語彙は、バイヤーがコミットしない透明性の開示が配信専用で出荷されるため、将来のマイナーで契約から乖離することが見込まれます(例: #3832 保留中の tracker_firing)。新しい qualifier キーは、いずれのサーフェスでも後続のマイナーで明示的に出荷されます。異種の値型: qualifier の値はほとんどが文字列の列挙ですが、attribution_window はオブジェクト値の期間です。コンシューマーは値の形状を知るためにキー名でディスパッチしなければならず(MUST)、構造化値の qualifier は正準(キーでソート)の深い等価性で結合します。
レポート間での qualifier セットのドリフト。 キャンペーンがフライト中に新しい qualifier を獲得した場合(例: 1 週目はクライアントサイドの発火のみで、2 週目に tracker_firing のパーティションを追加)、以前の期間の行は元の粒度で有効なままです。バイヤーは遡って再パーティションすべきではありません(SHOULD NOT)。supersedes_window によるレポートの置き換えが、ウィンドウレベルの改訂について文書化された経路です。
購入ごとの totals の形状はフラットのまま。 個々の購入は定義上シングル qualifier です。qualifier をまたぐのは購入横断の集計だけであり、パーティション化された形状を必要とします。購入ごとの totals.viewability は、独自の standard フィールドを持つフラットなオブジェクトのままです。
例:
metric_id を検査しなければなりません(MUST)。レートメトリクス(viewable_rate、completion_rate)は 0.0〜1.0、cost-per メトリクスは通貨、カウントメトリクスは非負の数値、ROAS は比率です。committed_metrics と同じディスパッチの慣習で、metric_id が型タグです。
よくあるシナリオ
単一のメディアバイ
複数のメディアバイ
日付範囲でのレポート
複数ステータスの取得
Buyer Reference での取得
アカウントスコープでの取得
メトリクスの定義
クエリの挙動
コンテキストベースのクエリ
media_buy_idsを指定しない場合、現在のセッションコンテキスト内のすべてのメディアバイを返す- コンテキストは
create_media_buyなど直前の操作で確立されます
ステータスフィルター
- 未指定時はデフォルトで
["active"] - 単一文字列 (
"active") でも配列 (["active", "paused"]) でも指定可能 - 有効なフィルター値はメディアバイのライフサイクルステータス:
pending_creatives、pending_start、active、paused、completed reporting_delayedとfailedは Webhook のコンテキストで返される配信/レポートのステータスであり、リクエストのフィルター値ではありません- 一部のレガシー統合は
pendingを出しうる。pending_startと同等として扱ってください
日付範囲
- 日付未指定の場合はキャンペーン全期間の配信データを返す
start_dateとend_dateは両方セットで指定しなければなりません——部分的な日付範囲は無効です- 日付形式:
YYYY-MM-DD - 開始を含み、終了を含まない:
start_dateは含まれ、end_dateは除外されます。例えばstart_date: "2026-01-01"、end_date: "2026-01-02"は 1 月 1 日のみのデータを返します。 - プロダクトは
reporting_capabilities.date_range_supportで日付範囲のサポートを宣言します date_range_support: "lifetime_only"のプロダクトは、start_date/end_dateを含むリクエストをDATE_RANGE_NOT_SUPPORTEDエラーで拒否しますdate_range_support: "date_range"のプロダクトは日付パラメータを受け付け、配信データをそれに応じてフィルタリングします- 長期範囲ではレスポンスサイズ削減のため日別内訳が間引かれる場合があります
メトリクスの有無
- 共通: Impressions, spend(すべてのプラットフォームで利用可能)
- フォーマット依存: Clicks, completed_views, completion_rate(在庫タイプとプラットフォーム能力に依存)
- オーディエンス: Reach, frequency(重複排除された計測を持つプラットフォームで利用可能)
- コマースアトリビューション: Conversions, conversion_value, roas, new_to_brand_rate(コマースメディアとストリーミングのプラットフォームで利用可能)
- エンゲージメント: Follows, saves, engagements, profile_visits(ソーシャルとストリーミングのプラットフォームで利用可能)
- アトリビューションウィンドウ:
attribution_windowは、コンバージョンアトリビューションに使われるルックバックウィンドウとモデルを表します(例: 14 日クリック、1 日ビュー、last_touch) - パッケージレベル: すべてのメトリクスが
by_packageで pacing_index とともに提供
データ鮮度
- レポートデータは通常 2〜4 時間の遅延があります
- リアルタイムのインプレッションカウントは提供されない
- ライブモニタリングではなく、定期レポートや最適化判断に利用します
reporting_capabilities.measurement_windows を持つプロダクトがこれらのタイムラインを宣言します。バイヤーは、合意された条件の billing_measurement で指定された measurement_window に対して照合します。計測条件は Accountability を、ライフサイクル全体は最適化とレポーティングを参照してください。
エラーハンドリング
パッケージレベルのメトリクス
by_package 配列はパッケージごとの配信詳細を次の主要フィールドとともに提供します。
Buyer Control:
paused: パッケージがバイヤーによって一時停止されているか(true/false)
delivery_status: システムが報告する動作状態:delivering- パッケージが配信中completed- 正常終了budget_exhausted- 予算を使い切ったflight_ended- 終了日に到達goal_met- インプレッション/コンバージョン目標を達成
pacing_index: 配信ペース(1.0 = 計画通り、1.0 未満 = 遅れ、1.0 超 = 先行)rate: 実効価格(例: CPM)pricing_model: 課金モデル (cpm, cpcv, cpp など)
missing_metrics: 拘束的なレポート契約が宣言していたが、このレポートで埋められていないメトリクス。各エントリは明示的なscope判別子を使います: 閉じたavailable-metric.json列挙由来のエントリには{ "scope": "standard", "metric_id": "completed_views" }、ベンダー定義メトリクスには{ "scope": "vendor", "vendor": { "domain": "..." }, "metric_id": "attention_units" }。標準エントリはcommitted_metricsの qualifier を反映するqualifierを運んでよい(MAY。例:{ "scope": "standard", "metric_id": "viewable_rate", "qualifier": { "viewability_standard": "mrc" } }は、GroupM のビューアビリティが報告されていても MRC のコミット欠如をフラグし、{ "scope": "standard", "metric_id": "completion_rate", "qualifier": { "completion_source": "vendor_attested" } }は、セラー証明の完了が報告されていてもベンダー証明のコミット欠如をフラグします——これらの経路は交換可能ではありません)。存在する場合はpackage.committed_metrics(committed_at < reporting_period.endのエントリにフィルタ)に対して照合され、存在しない場合はプロダクトの現在のreporting_capabilities.available_metricsとvendor_metricsにフォールバックします。空配列(または不在)は契約に対するクリーンな配信を示し、空でない場合はアカウンタビリティの違反を示します。セラーは、現在のmeasurement_windowでまだ計測できないメトリクス(例: live ウィンドウ中の post-IVT カウント)を除外しなければなりません(MUST)——それらは、より広いウィンドウがsupersedes_windowでこのレポートを置き換えるときに現れます(または現れません)。vendor_metric_values: プロダクトのreporting_capabilities.vendor_metricsが宣言したベンダー定義メトリクスの報告値(独自のアテンション、排出量、パネルのデモグラフィック、ブランドリフト調査など)。各エントリは{ vendor, metric_id, value, unit?, measurable_impressions?, breakdown? }を運びます。measurable_impressionsはカバレッジの分母です——ベンダーは自身の SDK が発火するか、パネルが一致するインプレッションのみをスコアリングするため、ベンダー計測が配信の 100% であることはまれです。バイヤーはカバレッジをmeasurable_impressions / impressionsとして計算します。measurable_impressionsが不在の場合、カバレッジは未指定です——バイヤーはカバレッジ率を計算したり、完全なカバレッジを仮定したりしてはなりません(MUST NOT)。宣言されたベンダーメトリクスがこの配列から完全に省略されている場合、計測が行われなかった(統合なし)と推論してください。JIC やパネルベースの共視聴調整、クレーム照合、信頼区間、パネルサイズは、購入時のシグナルターゲティング定義ではなく、通常breakdownの中でここに属します。
paused はバイヤーによる制御、delivery_status はシステム側の実態を表します。paused でなくても delivery_status: "budget_exhausted" の場合があります。
クリエイティブレベルのメトリクス
セラーがクリエイティブレベルのレポート(レポートケイパビリティのsupports_creative_breakdown)をサポートする場合、各パッケージにはクリエイティブごとの配信メトリクスを持つ by_creative 配列が含まれます。
各クリエイティブエントリは以下を含みます:
creative_id: クリエイティブ割り当てと一致するクリエイティブ識別子weight: レポート期間中のこのクリエイティブの配信ウェイト (0-100)- すべての標準配信メトリクス(impressions、spend、clicks、ctr など)
get_creative_delivery を使います。これはクリエイティブプロトコルのタスクです——クリエイティブプロトコルを実装する任意のエージェントで呼び出せます。supported_protocols に "creative" を宣言していれば、同じセラーエージェントであってもよい。セラーエージェントのクリエイティブ機能を参照してください。
カタログアイテムのレポート
カタログ駆動のパッケージ(catalog フィールドを持つパッケージ)では、セラーは各パッケージ内の by_catalog_item 配列でカタログアイテムごとの配信を返せます。
各エントリはカタログアイテムを識別し、標準の配信メトリクスを含みます:
これは任意です。アイテムレベルのレポートをサポートするセラーは
by_catalog_item を埋め、しないセラーは単に省略します。
ウィンドウ化プル復旧
reporting_webhook はバイヤーが選んだ reporting_frequency(hourly、daily、monthly)で発火します。受信側がトランスポートのリトライが尽きるほど長くオフラインだった場合、GET が同じスライスを再現できない限り、バイヤーはウィンドウごとの詳細を失います。time_granularity + include_window_breakdown がそのギャップを埋めます。
ケイパビリティの確認
セラーは、プル復旧で honor する粒度をreporting_capabilities.windowed_pull_granularities で宣言します。バイヤーは time_granularity を要求する前にケイパビリティを確認しなければなりません(MUST):
test=false
ウィンドウ化スライスの要求
test=false
レスポンスの形状
各メディアバイはレスポンスにwindows[] 配列を得ます:
test=false
window_start の昇順で並び、連続する行は隣接します(各行の window_end は次の行の window_start と等しい)。各スライスのペイロードは、同じウィンドウについて reporting_webhook が配信したであろうものと形状が揃っています——見逃した Webhook を照合するバイヤーは (media_buy_id, window_start) で結合します。
仕様上の契約
- ケイパビリティでスコープされた MUST — セラーは
windowed_pull_granularitiesにある任意の値についてtime_granularityの要求を honor しなければなりません(MUST)。宣言された集合の外のプルはUNSUPPORTED_GRANULARITYを返します。 - 非対称であることは誠実 — セラーは、プル向けに公開するより高い頻度の Webhook を出してよい(MAY)。
available_reporting_frequencies: ["hourly", "daily"]をwindowed_pull_granularities: ["daily"]とともに宣言するのは有効です。バイヤーはその頻度では hourly の Webhook を主として扱います。 - 同一形状での復旧 — スライスのペイロードは同じ粒度の Webhook 発火のペイロードを反映するため、バイヤーの照合パイプラインはトランスポート経路で分岐しません。
ディメンション別内訳
リクエストにreporting_dimensions を含めると、レスポンスは各 by_package エントリ内にディメンション別内訳の配列を含みます。各内訳エントリは delivery-metrics のすべてのフィールドに加え、ディメンション固有の識別子を継承します。
内訳の要求
test=false
limit(最大行数。geo・audience・placement は既定 25)と sort_by(sort-metric 列挙の任意の値。例: spend、impressions、clicks、roas——既定は spend の降順。セラーが要求されたメトリクスを報告しない場合は spend にフォールバック)を受け付けます。geo は geo_level(country、region、metro、postal_area)が必要です。特定のシステムを要求する場合は metro/postal レベルで system を含めます。ネイティブな郵便のリクエストは country も含みます(例: { "geo_level": "postal_area", "country": "US", "system": "zip" })。各リクエストは単一の geo_level を使います——複数の粒度(例: country と region)には、別々のリクエストを行ってください。サポートされないディメンションはレスポンスから黙って省略されますが、不正なリクエスト(例: geo_level のない geo)は検証エラーを返します。内訳はディメンション単位のみです——ディメンション横断の交差(例: device_type × geo)はサポートされません。
利用可能なディメンション
どのディメンションが利用可能かはプロダクトの
reporting_capabilities で確認してください。同じセラーの異なるプロダクトが異なる内訳をサポートしうるため、プロダクトレベルのケイパビリティが権威的です。
supports_geo_breakdown は利用可能なレベルとシステムを宣言するオブジェクトで、この表の他のケイパビリティ宣言はブール値のフラグです。supports_geo_breakdown 内では、country と region はブール値で、metro は metro-system の値でキー付けされ、ネイティブな postal_area は ISO 3166-1 alpha-2 の国でキー付けされ、国ローカルな postal-system 値の配列を持ちます。geo の行は geo_level: "metro" と "postal_area" で system を使います。ネイティブな郵便の行は country も含みます。非推奨の国融合型の郵便システムは互換性のため引き続き受け付けられます。
プレースメントのアイデンティティはパブリッシャースコープです。プレースメント行は publisher_domain——プロダクトの placements[] エントリ由来のパブリッシャー名前空間——を運んでよく(MAY)、それが存在する場合、バイヤーはマルチパブリッシャープロダクトについて {publisher_domain, placement_id} を安定したプレースメントのアイデンティティとして扱えます。セラーは、プロダクトのプレースメントがそれを運ぶ場合は常に publisher_domain を出すべきです(SHOULD。kind: "publisher_ref" では常に真)。セラーがそれを省略してよいのは、セラーエージェント自身のドメインが名前空間であるレガシーな単一パブリッシャーの文脈における kind: "seller_inline" のプレースメントに限られます。publisher_domain が省略された場合、バイヤーはそのレガシーな単一パブリッシャーの文脈でのみ placement_id をセラーエージェント自身のパブリッシャードメインに対して解釈してよく(MAY)、それ以外ではパブリッシャー横断のプレースメントキーを推測すべきではありません。各プレースメントは正確に一つのパブリッシャー名前空間に属するため、publisher_domain は単一値です。
切り詰め
各内訳配列には兄弟のブールフラグ(例:by_geo_truncated)があります。true のとき、返された集合を超える追加行が存在します。false のとき、リストは完全です。セラーは、対応する内訳配列が存在する場合は常に truncated フラグを返さなければなりません(MUST)。行は要求された sort_by メトリクスの降順で並びます。
オーディエンスソース
audience_source フィールドは、オーディエンスセグメントがどこに由来するかを示します:
ベストプラクティス
1. 日付範囲のサポートを確認する 日付でフィルタした配信を要求する前に、プロダクトのreporting_capabilities.date_range_support を確認します。lifetime_only のサポートを持つプロダクトは日付範囲のリクエストを拒否します——代わりに start_date と end_date を省略してキャンペーン全期間のデータを取得してください。
2. 日付範囲を指定して分析する
日付範囲をサポートするプロダクトでは、期間比較やトレンド分析のために日付を指定します。
3. Pacing Index を監視する
0.95〜1.05 を目標とし、逸脱している場合は配信問題を疑う。
4. 日別内訳を確認する
配信パターンや平日/週末での差分を把握します。
5. パッケージ性能を比較する
by_package 内訳で最も成果の高い在庫を特定します。paused と delivery_status の両方を確認し、配信されない理由を把握します。
6. ステータス変化を追跡する
複数ステータスのクエリで、キャンペーンが停止/完了した理由を把握します。
配信後のガバナンス検証
配信レポートは最後のステップではありません。キャンペーンガバナンスが有効な場合、配信データはガバナンス検証に流れ込み、認可されていないサプライパス、ジオのドリフト、ペーシング違反を検出します。 ガバナンスのフィードバックループ:get_media_buy_deliveryで配信データを取得report_plan_outcomeでガバナンスエージェントに結果を報告- ガバナンスエージェントが実際の配信を計画パラメータと比較(ドリフト検出)
validate_property_deliveryでプロパティの配信を検証し、認可されていないサプライパスを検出
このフィードバックループがなければ、配信データは報告されても検証されません。予算超過、ペーシングの乖離、ジオのドリフト、認可されていないサプライパスが検出されないままになります。
次のステップ
配信データ取得後にできること:- キャンペーンを最適化:
update_media_buyで予算、ペーシング、ターゲティングを調整 - フィードバックを共有:
provide_performance_feedbackで結果をセラーに共有 - クリエイティブを更新: ライブラリ対応のセラーには
sync_creativesを、インライン専用のセラーにはupdate_media_buyのインラインpackages[].creativesを使用 - フォローアップキャンペーンを作成: インサイトに基づき
create_media_buyを実行
さらに学ぶ
- Media Buy Lifecycle - キャンペーンワークフロー全体
- Async Operations - 非同期パターンとステータス処理
- Performance Optimization - 配信データを用いた最適化