Skip to main content
メディアバイのレポーティングに必要な配信メトリクスとパフォーマンスデータを取得します。 応答時間: 約 60 秒(レポーティングクエリ) リクエストスキーマ: /schemas/v2/media-buy/get-media-buy-delivery-request.json レスポンススキーマ: /schemas/v2/media-buy/get-media-buy-delivery-response.json

リクエストパラメーター

ParameterTypeRequiredDescription
media_buy_idsstring[]No*取得するメディアバイ ID の配列
buyer_refsstring[]No*バイヤーリファレンス ID の配列
status_filterstring | string[]Noステータスフィルター: "active", "pending", "paused", "completed", "failed", "all"。デフォルトは ["active"]
start_datestringNoレポート開始日 (YYYY-MM-DD)
end_datestringNoレポート終了日 (YYYY-MM-DD)
*media_buy_idsbuyer_refs のいずれかを指定できます。どちらも未指定の場合、現在のセッションコンテキスト内のすべてのメディアバイを返します。

レスポンス

集計とメディアバイごとの内訳を含む配信レポートを返します。
FieldDescription
reporting_periodレポート対象期間(開始/終了タイムスタンプ)
currencyISO 4217 通貨コード (USD, EUR, GBP など)
aggregated_totalsすべてのメディアバイを合算したメトリクス(impressions、spend、clicks、video_completions、media_buy_count)
media_buy_deliveriesメディアバイごとの配信データ配列

Media Buy Delivery オブジェクト

FieldDescription
media_buy_idメディアバイ ID
buyer_refバイヤーのリファレンス ID
status現在のステータス (pending, active, paused, completed, failed)
totals集計メトリクス(impressions、spend、clicks、ctr、video_completions、completion_rate)
by_packagedelivery_status、paused 状態、pacing_index を含むパッケージレベルの内訳
daily_breakdown日別配信(date、impressions、spend)
完全なフィールド一覧はスキーマを参照してください。

よくあるシナリオ

単一のメディアバイ

import { testAgent } from "@adcp/client/testing";
import { GetMediaBuyDeliveryResponseSchema } from "@adcp/client";

// 単一メディアバイの配信レポートを取得
const result = await testAgent.getMediaBuyDelivery({
  media_buy_ids: ["mb_12345"],
  start_date: "2024-02-01",
  end_date: "2024-02-07"
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = GetMediaBuyDeliveryResponseSchema.parse(result.data);

// 判別共用体レスポンスのエラーを確認
if ("errors" in validated && validated.errors) {
  throw new Error(`Query failed: ${JSON.stringify(validated.errors)}`);
}

console.log(
  `Delivered ${validated.aggregated_totals.impressions.toLocaleString()} impressions`
);
console.log(`Spend: $${validated.aggregated_totals.spend.toFixed(2)}`);
if (validated.media_buy_deliveries.length > 0) {
  console.log(
    `CTR: ${(validated.media_buy_deliveries[0].totals.ctr * 100).toFixed(2)}%`
  );
}

複数のメディアバイ

import { testAgent } from "@adcp/client/testing";
import { GetMediaBuyDeliveryResponseSchema } from "@adcp/client";

// コンテキスト内のアクティブなメディアバイをすべて取得
const result = await testAgent.getMediaBuyDelivery({
  status_filter: "active",
  start_date: "2024-02-01",
  end_date: "2024-02-07"
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = GetMediaBuyDeliveryResponseSchema.parse(result.data);

if ("errors" in validated && validated.errors) {
  throw new Error(`Query failed: ${JSON.stringify(validated.errors)}`);
}

console.log(`${validated.aggregated_totals.media_buy_count} active campaigns`);
console.log(
  `Total impressions: ${validated.aggregated_totals.impressions.toLocaleString()}`
);
console.log(`Total spend: $${validated.aggregated_totals.spend.toFixed(2)}`);

// キャンペーンごとに確認
validated.media_buy_deliveries.forEach((delivery) => {
  console.log(
    `${delivery.media_buy_id}: ${delivery.totals.impressions.toLocaleString()} impressions, CTR ${(delivery.totals.ctr * 100).toFixed(2)}%`
  );
});

日付範囲でのレポート

import { testAgent } from "@adcp/client/testing";
import { GetMediaBuyDeliveryResponseSchema } from "@adcp/client";

// 月初から現在までのパフォーマンスを取得
const now = new Date();
const monthStart = new Date(now.getFullYear(), now.getMonth(), 1);
const dateFormat = (date) => date.toISOString().split("T")[0];

const result = await testAgent.getMediaBuyDelivery({
  media_buy_ids: ["mb_12345"],
  start_date: dateFormat(monthStart),
  end_date: dateFormat(now)
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = GetMediaBuyDeliveryResponseSchema.parse(result.data);

if ("errors" in validated && validated.errors) {
  throw new Error(`Query failed: ${JSON.stringify(validated.errors)}`);
}

if (validated.media_buy_deliveries.length > 0) {
  // 日別内訳を分析
  const dailyBreakdown = validated.media_buy_deliveries[0].daily_breakdown;
  if (dailyBreakdown && dailyBreakdown.length > 0) {
    console.log(
      `Daily average: ${Math.round(validated.aggregated_totals.impressions / dailyBreakdown.length).toLocaleString()} impressions`
    );

    // ピーク日を特定
    const peakDay = dailyBreakdown.reduce((max, day) =>
      day.impressions > max.impressions ? day : max
    );
    console.log(
      `Peak day: ${peakDay.date} with ${peakDay.impressions.toLocaleString()} impressions`
    );
  }
}

複数ステータスの取得

import { testAgent } from "@adcp/client/testing";
import { GetMediaBuyDeliveryResponseSchema } from "@adcp/client";

// アクティブと一時停止中のキャンペーンを取得
const result = await testAgent.getMediaBuyDelivery({
  status_filter: ["active", "paused"],
  start_date: "2024-02-01",
  end_date: "2024-02-07"
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = GetMediaBuyDeliveryResponseSchema.parse(result.data);

if ("errors" in validated && validated.errors) {
  throw new Error(`Query failed: ${JSON.stringify(validated.errors)}`);
}

// ステータス別にグループ化
const byStatus = validated.media_buy_deliveries.reduce((acc, delivery) => {
  if (!acc[delivery.status]) acc[delivery.status] = [];
  acc[delivery.status].push(delivery);
  return acc;
}, {});

console.log(`Active campaigns: ${byStatus.active?.length || 0}`);
console.log(`Paused campaigns: ${byStatus.paused?.length || 0}`);

// パフォーマンスが低いキャンペーンを特定
byStatus.paused?.forEach((delivery) => {
  if (delivery.by_package && delivery.by_package.length > 0) {
    const avgPacing =
      delivery.by_package.reduce((sum, pkg) => sum + pkg.pacing_index, 0) /
      delivery.by_package.length;
    console.log(
      `${delivery.media_buy_id}: paused with ${(avgPacing * 100).toFixed(0)}% pacing`
    );
  }
});

Buyer Reference での取得

import { testAgent } from "@adcp/client/testing";
import { GetMediaBuyDeliveryResponseSchema } from "@adcp/client";

// buyer_ref ベースで複数キャンペーンを比較
const result = await testAgent.getMediaBuyDelivery({
  buyer_refs: ["nike_q1_campaign_2024", "nike_q1_retargeting_2024"]
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = GetMediaBuyDeliveryResponseSchema.parse(result.data);

if ("errors" in validated && validated.errors) {
  throw new Error(`Query failed: ${JSON.stringify(validated.errors)}`);
}

console.log(
  `Total lifetime impressions: ${validated.aggregated_totals.impressions.toLocaleString()}`
);
console.log(
  `Total lifetime spend: $${validated.aggregated_totals.spend.toFixed(2)}`
);

validated.media_buy_deliveries.forEach((delivery) => {
  if (delivery.totals.impressions > 0) {
    const cpm = (delivery.totals.spend / delivery.totals.impressions) * 1000;
    console.log(
      `${delivery.buyer_ref}: CPM $${cpm.toFixed(2)}, CTR ${(delivery.totals.ctr * 100).toFixed(2)}%`
    );
  }
});

メトリクスの定義

MetricDefinition
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_idsbuyer_refs も指定しない場合、現在のセッションコンテキスト内のすべてのメディアバイを返す
  • コンテキストは create_media_buy など直前の操作で確立される

ステータスフィルター

  • 未指定時はデフォルトで ["active"]
  • 単一文字列 ("active") でも配列 (["active", "paused"]) でも指定可能
  • すべてのステータスを取得するには "all" を使用

日付範囲

  • 日付未指定の場合はライフタイム配信データを返す
  • 日付形式: YYYY-MM-DD
  • 長期範囲ではレスポンスサイズ削減のため日別内訳が間引かれる場合がある

メトリクスの有無

  • 共通: Impressions, spend(すべてのプラットフォームで利用可能)
  • フォーマット依存: Clicks, video completions(在庫タイプとプラットフォーム能力に依存)
  • パッケージレベル: すべてのメトリクスが by_package で pacing_index とともに提供

データ鮮度

  • レポートデータは通常 2〜4 時間の遅延がある
  • リアルタイムのインプレッションカウントは提供されない
  • ライブモニタリングではなく、定期レポートや最適化判断に利用する

エラーハンドリング

Error CodeDescriptionResolution
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)
System State:
  • delivery_status: システムが報告する動作状態:
    • delivering - パッケージが配信中
    • completed - 正常終了
    • budget_exhausted - 予算を使い切った
    • flight_ended - 終了日に到達
    • goal_met - インプレッション/コンバージョン目標を達成
Performance:
  • 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 内訳で最も成果の高い在庫を特定します。pauseddelivery_status の両方を確認し、配信されない理由を把握します。 5. ステータス変化を追跡する 複数ステータスのクエリで、キャンペーンが停止/完了した理由を把握します。

次のステップ

配信データ取得後にできること:
  1. キャンペーンを最適化: update_media_buy で予算、ペーシング、ターゲティングを調整
  2. フィードバックを共有: provide_performance_feedback で結果をセラーに共有
  3. クリエイティブを更新: sync_creatives で成果の低いアセットを更新
  4. フォローアップキャンペーンを作成: インサイトに基づき create_media_buy を実行

さらに学ぶ