/schemas/v2/media-buy/get-media-buy-delivery-request.json
レスポンススキーマ: /schemas/v2/media-buy/get-media-buy-delivery-response.json
リクエストパラメーター
| Parameter | Type | Required | Description |
|---|---|---|---|
media_buy_ids | string[] | No* | 取得するメディアバイ ID の配列 |
buyer_refs | string[] | No* | バイヤーリファレンス ID の配列 |
status_filter | string | string[] | No | ステータスフィルター: "active", "pending", "paused", "completed", "failed", "all"。デフォルトは ["active"] |
start_date | string | No | レポート開始日 (YYYY-MM-DD) |
end_date | string | No | レポート終了日 (YYYY-MM-DD) |
media_buy_ids と buyer_refs のいずれかを指定できます。どちらも未指定の場合、現在のセッションコンテキスト内のすべてのメディアバイを返します。
レスポンス
集計とメディアバイごとの内訳を含む配信レポートを返します。| Field | Description |
|---|---|
reporting_period | レポート対象期間(開始/終了タイムスタンプ) |
currency | ISO 4217 通貨コード (USD, EUR, GBP など) |
aggregated_totals | すべてのメディアバイを合算したメトリクス(impressions、spend、clicks、video_completions、media_buy_count) |
media_buy_deliveries | メディアバイごとの配信データ配列 |
Media Buy Delivery オブジェクト
| Field | Description |
|---|---|
media_buy_id | メディアバイ ID |
buyer_ref | バイヤーのリファレンス ID |
status | 現在のステータス (pending, active, paused, completed, failed) |
totals | 集計メトリクス(impressions、spend、clicks、ctr、video_completions、completion_rate) |
by_package | delivery_status、paused 状態、pacing_index を含むパッケージレベルの内訳 |
daily_breakdown | 日別配信(date、impressions、spend) |
よくあるシナリオ
単一のメディアバイ
複数のメディアバイ
日付範囲でのレポート
複数ステータスの取得
Buyer Reference での取得
メトリクスの定義
| Metric | Definition |
|---|---|
| Impressions | 広告が表示された回数 |
| Spend | 指定通貨での支出額 |
| Clicks | 広告クリック数(利用可能な場合) |
| CTR | クリック率 (clicks/impressions) |
| Video Completions | 動画の完視聴回数 |
| Completion Rate | 動画の完視聴/動画インプレッション |
| Pacing Index | 実績 vs 期待の配信速度 (1.0 = 計画通り、<1.0 遅れ、>1.0 先行) |
| CPM | インプレッション 1,000 件あたりのコスト (spend/impressions * 1000) |
クエリの挙動
コンテキストベースのクエリ
media_buy_idsもbuyer_refsも指定しない場合、現在のセッションコンテキスト内のすべてのメディアバイを返す- コンテキストは
create_media_buyなど直前の操作で確立される
ステータスフィルター
- 未指定時はデフォルトで
["active"] - 単一文字列 (
"active") でも配列 (["active", "paused"]) でも指定可能 - すべてのステータスを取得するには
"all"を使用
日付範囲
- 日付未指定の場合はライフタイム配信データを返す
- 日付形式:
YYYY-MM-DD - 長期範囲ではレスポンスサイズ削減のため日別内訳が間引かれる場合がある
メトリクスの有無
- 共通: Impressions, spend(すべてのプラットフォームで利用可能)
- フォーマット依存: Clicks, video completions(在庫タイプとプラットフォーム能力に依存)
- パッケージレベル: すべてのメトリクスが
by_packageで pacing_index とともに提供
データ鮮度
- レポートデータは通常 2〜4 時間の遅延がある
- リアルタイムのインプレッションカウントは提供されない
- ライブモニタリングではなく、定期レポートや最適化判断に利用する
エラーハンドリング
| Error Code | Description | Resolution |
|---|---|---|
AUTH_REQUIRED | 認証が必要 | 認証情報を提供する |
MEDIA_BUY_NOT_FOUND | メディアバイが存在しない | media_buy_id を確認する |
INVALID_DATE_RANGE | 不正な開始/終了日 | YYYY-MM-DD 形式で start < end にする |
CONTEXT_REQUIRED | コンテキストにメディアバイがない | media_buy_ids か buyer_refs を指定する |
INVALID_STATUS_FILTER | 無効なステータス値 | active, pending, paused, completed, failed, all のいずれかを使用 |
パッケージレベルのメトリクス
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 など)
paused はバイヤーによる制御、delivery_status はシステム側の実態を表します。paused でなくても delivery_status: "budget_exhausted" の場合があります。
ベストプラクティス
1. 日付範囲を指定して分析する 期間比較やトレンド分析のために日付範囲を指定します。 2. Pacing Index を監視する 0.95〜1.05 を目標とし、逸脱している場合は配信問題を疑う。 3. 日別内訳を確認する 配信パターンや平日/週末での差分を把握します。 4. パッケージ性能を比較するby_package 内訳で最も成果の高い在庫を特定します。paused と delivery_status の両方を確認し、配信されない理由を把握します。
5. ステータス変化を追跡する
複数ステータスのクエリで、キャンペーンが停止/完了した理由を把握します。
次のステップ
配信データ取得後にできること:- キャンペーンを最適化:
update_media_buyで予算、ペーシング、ターゲティングを調整 - フィードバックを共有:
provide_performance_feedbackで結果をセラーに共有 - クリエイティブを更新:
sync_creativesで成果の低いアセットを更新 - フォローアップキャンペーンを作成: インサイトに基づき
create_media_buyを実行
さらに学ぶ
- Media Buy Lifecycle - キャンペーンワークフロー全体
- Async Operations - 非同期パターンとステータス処理
- Performance Optimization - 配信データを用いた最適化