Documentation Index
Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt
Use this file to discover all available pages before exploring further.
メディアバイのレポーティングに必要な配信メトリクスとパフォーマンスデータを取得します。
応答時間: 約 60 秒(レポーティングクエリ)
リクエストスキーマ: /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 | メディアバイごとの配信データ配列 |
| 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) |
完全なフィールド一覧はスキーマを参照してください。
よくあるシナリオ
単一のメディアバイ
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)}%`
);
}
});
メトリクスの定義
| 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)
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 内訳で最も成果の高い在庫を特定します。paused と delivery_status の両方を確認し、配信されない理由を把握します。
5. ステータス変化を追跡する
複数ステータスのクエリで、キャンペーンが停止/完了した理由を把握します。
次のステップ
配信データ取得後にできること:
- キャンペーンを最適化:
update_media_buy で予算、ペーシング、ターゲティングを調整
- フィードバックを共有:
provide_performance_feedback で結果をセラーに共有
- クリエイティブを更新:
sync_creatives で成果の低いアセットを更新
- フォローアップキャンペーンを作成: インサイトに基づき
create_media_buy を実行
さらに学ぶ