> ## 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.
# get_media_buy_delivery
> get_media_buy_delivery タスク — 稼働中の AdCP キャンペーンについてインプレッション、消化額、ペーシング、ディメンション別内訳を取得します。カスタム日付範囲とメトリクスのフィルタリングをサポートします。
メディアバイのレポーティングに必要な配信メトリクスとパフォーマンスデータを取得します。
**応答時間**: 約 60 秒（レポーティングクエリ）
## スコープ
`get_media_buy_delivery` は、基盤となるキャンペーンがどう作成されたかに関わらず、[`get_media_buys`](/docs/media-buy/task-reference/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`](https://adcontextprotocol.org/schemas/v3/media-buy/get-media-buy-delivery-request.json)
**レスポンススキーマ**: [`/schemas/v3/media-buy/get-media-buy-delivery-response.json`](https://adcontextprotocol.org/schemas/v3/media-buy/get-media-buy-delivery-response.json)
## リクエストパラメーター
| Parameter | Type | Required | Description |
| -------------------------- | -------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account` | [account-ref](/docs/building/by-layer/L2/accounts-and-agents#account-references) | No | アカウント参照。`{ "account_id": "..." }` または、セラーが暗黙的な解決をサポートする場合は `{ "brand": {...}, "operator": "..." }` を渡します。このアカウントに属するメディアバイのみを返します。省略時は、アクセス可能なすべてのアカウントにわたるデータを返します。 |
| `media_buy_ids` | string\[] | No\* | 取得するメディアバイ ID の配列 |
| `status_filter` | string \| string\[] | No | ステータスフィルター: `"pending_creatives"`、`"pending_start"`、`"active"`、`"paused"`、`"completed"`。省略時は `["active"]` がデフォルト。 |
| `start_date` | string | No | レポート開始日 (YYYY-MM-DD)、**含む**。キャンペーン全期間のデータを得るには省略します。プロダクトが `date_range` をサポートする場合のみ受け付けられます。 |
| `end_date` | string | No | レポート終了日 (YYYY-MM-DD)、**含まない**。キャンペーン全期間のデータを得るには省略します。プロダクトが `date_range` をサポートする場合のみ受け付けられます。 |
| `reporting_dimensions` | object | No | `by_package` 内のディメンション別内訳を要求します。デフォルトで有効化するには、キーを空オブジェクトとして含めます（例: `"device_type": {}`）。キー: `geo`、`device_type`、`device_platform`、`audience`、`placement`。各キーは任意の `limit`（geo・audience・placement は既定 25）と `sort_by`（sort-metric 列挙、既定: `spend`）を受け付けます。geo は `geo_level`（リクエストごとに一つ）が必要で、特定のシステムを要求する場合は metro/postal レベルで `system` を含めます。サポートされないディメンションは黙って省略され、不正なリクエストは検証エラーを返します。 |
| `time_granularity` | string | No | プル復旧のためのウィンドウごとのスライス粒度。`reporting_webhook.reporting_frequency` の語彙（`hourly`、`daily`、`monthly`）に一致します。設定すると、レスポンスは同じ粒度の Webhook 発火と形状が揃った `windows[]` スライスを含みます。ケイパビリティでスコープされます——値はプロダクトの `reporting_capabilities.windowed_pull_granularities` に含まれていなければなりません（MUST）。[ウィンドウ化プル復旧](#windowed-pull-recovery)参照。 |
| `include_window_breakdown` | boolean | No | `true`（かつ `time_granularity` が設定されている）とき、各メディアバイに `windows[]` 配列を含めます。既定は `false`。`time_granularity` が省略された場合は無視されます。 |
> **日付範囲の挙動**: 日付範囲は**開始を含み、終了を含みません**。例えば `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"` を使います。
**日付範囲の例**:
| start\_date | end\_date | Data Returned |
| ------------ | ------------ | ---------------- |
| `2026-01-01` | `2026-01-02` | 1 月 1 日のみ（1 日） |
| `2026-01-01` | `2026-01-08` | 1 月 1 日〜7 日（7 日） |
| `2026-01-01` | `2026-02-01` | 1 月全体（31 日） |
| `2026-01-15` | `2026-01-16` | 1 月 15 日のみ（1 日） |
\*`media_buy_ids` は結果を特定のメディアバイに絞り込みます。いずれも指定しない場合、現在のセッションコンテキスト内のすべてのメディアバイを返します。
## レスポンス
集計とメディアバイごとの内訳を含む配信レポートを返します。
| Field | Description |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reporting_period` | レポート対象期間（開始/終了タイムスタンプ） |
| `currency` | ISO 4217 通貨コード (USD, EUR, GBP など) |
| `attribution_window` | アトリビューション手法: `post_click` と `post_view`（期間オブジェクト）、および `model`（last\_touch、first\_touch、linear、time\_decay、data\_driven） |
| `aggregated_totals` | すべてのメディアバイを合算したメトリクス（impressions, spend, clicks, views, completed\_views, conversions, conversion\_value, roas, new\_to\_brand\_rate, cost\_per\_acquisition, completion\_rate, reach, reach\_unit, frequency, media\_buy\_count, metric\_aggregates） |
| `media_buy_deliveries` | メディアバイごとの配信データ配列 |
### 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](https://github.com/adcontextprotocol/adcp/issues/4905)）。全体像は[移行 › `media_buy_status`](/docs/reference/migration/media-buy-status)を参照してください。
| Field | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `media_buy_id` | メディアバイ ID |
| `status` | 現在のステータス（`pending_creatives`、`pending_start`、`active`、`paused`、`completed`）。Webhook のコンテキストでは `reporting_delayed` や `failed` にもなりうる。`create_media_buy` / `update_media_buy` の成功レスポンスの `media_buy_status` に対応します（上記 3.1 の語彙注記）。 |
| `totals` | 集計メトリクス（impressions, spend, clicks, ctr, conversions, conversion\_value, roas, new\_to\_brand\_rate） |
| `by_package` | delivery\_status、paused 状態、pacing\_index を含むパッケージレベルの内訳 |
| `daily_breakdown` | 日別配信（date, impressions, spend, conversions, conversion\_value, roas, new\_to\_brand\_rate） |
完全なフィールド一覧は[スキーマ](https://adcontextprotocol.org/schemas/v3/media-buy/get-media-buy-delivery-response.json)を参照してください。
### 最終値と暫定値
配信行は、**その計測ウィンドウについて最終**であるか、そうでないかのいずれかです。最終とは、セラーがその期間についてこれらの数値を確定——これ以上の改訂なし——とみなし、購入が作成された際の `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`](/docs/media-buy/advanced-topics/billing-authority) で宣言されます:
* **セラー証明**（`billing_measurement` が不在、またはセラー自身のアドサーバーを指名する場合の既定）: `get_media_buy_delivery` の最終行に基づいて請求します。
* **ベンダー証明**（購入で指名された第三者計測ベンダー——例: Nielsen、IAS、DV、MOAT）: 指名されたベンダーの権威ある数値に基づいて請求します。運用上は、セラーがベンダーから取得して `is_final: true` を伴って `get_media_buy_delivery` で公開するのが最も一般的です。バイヤーがベンダーとの関係を保持する場合は、バイヤーが `final: true` と `finalized_at` を設定して [`report_usage`](/docs/accounts/tasks/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`](/docs/media-buy/advanced-topics/accountability) と帯域外の交渉で解決します。
エンドツーエンドのフローは[請求の権威](/docs/media-buy/advanced-topics/billing-authority)を参照してください。構造化された紛争タスク——ワイヤー上で配信の紛争を開始・遷移・解決する——は AdCP 3.2 を目標としています。
### 集計メトリクスのパーティション（`metric_aggregates`）
**qualifier**（計測標準、透明性の開示）によって変わる購入横断の配信値は、フラットなスカラーではなく `aggregated_totals.metric_aggregates` のパーティション化された配列として報告されます。これは集計レイヤーでの「リンゴとオレンジの合計」問題を解決します: MRC と GroupM のビューアビリティは実質的に異なる閾値を定義しており、単一のレートに合算してはなりません。
各行は `package.committed_metrics` と `by_package[].missing_metrics` と同じ原子単位を運びます:
```
committed_metrics row : { scope, metric_id, qualifier, committed_at }
missing_metrics row : { scope, metric_id, qualifier }
metric_aggregates row : { scope, metric_id, qualifier, value, ...components }
```
**照合は `(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` フィールドを持つフラットなオブジェクトのままです。
例:
```json theme={null}
{
"aggregated_totals": {
"impressions": 1000000,
"spend": 5000.00,
"media_buy_count": 3,
"metric_aggregates": [
{
"scope": "standard",
"metric_id": "viewable_rate",
"qualifier": { "viewability_standard": "mrc" },
"value": 0.7286,
"measurable_impressions": 700000,
"viewable_impressions": 510000
},
{
"scope": "standard",
"metric_id": "viewable_rate",
"qualifier": { "viewability_standard": "groupm" },
"value": 0.55,
"measurable_impressions": 180000,
"viewable_impressions": 99000
}
]
}
}
```
**値の型ディスパッチ。** バイヤーエージェントは算術を行う前に `metric_id` を検査しなければなりません（MUST）。レートメトリクス（`viewable_rate`、`completion_rate`）は 0.0〜1.0、cost-per メトリクスは通貨、カウントメトリクスは非負の数値、ROAS は比率です。`committed_metrics` と同じディスパッチの慣習で、`metric_id` が型タグです。
## よくあるシナリオ
### 単一のメディアバイ
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { GetMediaBuyDeliveryResponseSchema } from "@adcp/sdk";
// 単一メディアバイの配信レポートを取得
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)}%`
);
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
from adcp.types import GetMediaBuyDeliveryRequest
async def main():
# 単一メディアバイの配信レポートを取得
result = await test_agent.get_media_buy_delivery(
GetMediaBuyDeliveryRequest(
media_buy_ids=['mb_12345'],
start_date='2024-02-01',
end_date='2024-02-07'
)
)
# 判別共用体レスポンスのエラーを確認
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Query failed: {result.errors}")
print(f"Delivered {result.aggregated_totals.impressions:,} impressions")
print(f"Spend: ${result.aggregated_totals.spend:.2f}")
if result.media_buy_deliveries:
print(f"CTR: {result.media_buy_deliveries[0].totals.ctr * 100:.2f}%")
asyncio.run(main())
```
### 複数のメディアバイ
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { GetMediaBuyDeliveryResponseSchema } from "@adcp/sdk";
// コンテキスト内のアクティブなメディアバイをすべて取得
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)}%`
);
});
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
from adcp.types import GetMediaBuyDeliveryRequest
async def main():
# コンテキスト内のアクティブなメディアバイをすべて取得
result = await test_agent.get_media_buy_delivery(
GetMediaBuyDeliveryRequest(
status_filter='active',
start_date='2024-02-01',
end_date='2024-02-07'
)
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Query failed: {result.errors}")
print(f"{result.aggregated_totals.media_buy_count} active campaigns")
print(f"Total impressions: {result.aggregated_totals.impressions:,}")
print(f"Total spend: ${result.aggregated_totals.spend:.2f}")
# キャンペーンごとに確認
for delivery in result.media_buy_deliveries:
print(f"{delivery.media_buy_id}: {delivery.totals.impressions:,} impressions, CTR {delivery.totals.ctr * 100:.2f}%")
asyncio.run(main())
```
### 日付範囲でのレポート
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { GetMediaBuyDeliveryResponseSchema } from "@adcp/sdk";
// 月初から現在までのパフォーマンスを取得
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`
);
}
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
from adcp.types import GetMediaBuyDeliveryRequest
from datetime import date
async def main():
# 月初から現在までのパフォーマンスを取得
today = date.today()
month_start = date(today.year, today.month, 1)
result = await test_agent.get_media_buy_delivery(
GetMediaBuyDeliveryRequest(
media_buy_ids=['mb_12345'],
start_date=str(month_start),
end_date=str(today)
)
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Query failed: {result.errors}")
if result.media_buy_deliveries:
# 日別内訳を分析
daily_breakdown = result.media_buy_deliveries[0].daily_breakdown
if daily_breakdown:
daily_avg = result.aggregated_totals.impressions // len(daily_breakdown)
print(f"Daily average: {daily_avg:,} impressions")
# ピーク日を特定
peak_day = max(daily_breakdown, key=lambda d: d.impressions)
print(f"Peak day: {peak_day.date} with {peak_day.impressions:,} impressions")
asyncio.run(main())
```
### 複数ステータスの取得
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { GetMediaBuyDeliveryResponseSchema } from "@adcp/sdk";
// アクティブと一時停止中のキャンペーンを取得
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`
);
}
});
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
from adcp.types import GetMediaBuyDeliveryRequest
from collections import defaultdict
async def main():
# アクティブと一時停止中のキャンペーンを取得
result = await test_agent.get_media_buy_delivery(
GetMediaBuyDeliveryRequest(
status_filter=['active', 'paused'],
start_date='2024-02-01',
end_date='2024-02-07'
)
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Query failed: {result.errors}")
# ステータス別にグループ化
by_status = defaultdict(list)
for delivery in result.media_buy_deliveries:
by_status[delivery.status].append(delivery)
print(f"Active campaigns: {len(by_status['active'])}")
print(f"Paused campaigns: {len(by_status['paused'])}")
# パフォーマンスが低いキャンペーンを特定
for delivery in by_status['paused']:
if delivery.by_package:
avg_pacing = sum(pkg.pacing_index for pkg in delivery.by_package) / len(delivery.by_package)
print(f"{delivery.media_buy_id}: paused with {avg_pacing * 100:.0f}% pacing")
asyncio.run(main())
```
### Buyer Reference での取得
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { GetMediaBuyDeliveryResponseSchema } from "@adcp/sdk";
// メディアバイ ID の代わりに buyer reference で検索
const result = await testAgent.getMediaBuyDelivery({
media_buy_ids: ["acme_q1_campaign_2024", "acme_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.media_buy_id}: CPM $${cpm.toFixed(2)}, CTR ${(delivery.totals.ctr * 100).toFixed(2)}%`
);
}
});
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
from adcp.types import GetMediaBuyDeliveryRequest
async def main():
# メディアバイ ID の代わりに buyer reference で検索
result = await test_agent.get_media_buy_delivery(
GetMediaBuyDeliveryRequest(
media_buy_ids=['acme_q1_campaign_2024', 'acme_q1_retargeting_2024']
)
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Query failed: {result.errors}")
# ライフタイム配信データ（日付範囲を指定しない場合）
print(f"Total lifetime impressions: {result.aggregated_totals.impressions:,}")
print(f"Total lifetime spend: ${result.aggregated_totals.spend:.2f}")
# キャンペーン比較
for delivery in result.media_buy_deliveries:
if delivery.totals.impressions > 0:
cpm = (delivery.totals.spend / delivery.totals.impressions) * 1000
print(f"{delivery.media_buy_id}: CPM ${cpm:.2f}, CTR {delivery.totals.ctr * 100:.2f}%")
asyncio.run(main())
```
### アカウントスコープでの取得
```javascript JavaScript test=false theme={null}
import { testAgent } from '@adcp/sdk/testing';
import { GetMediaBuyDeliveryResponseSchema } from '@adcp/sdk';
// Get delivery for a specific advertiser account
const result = await testAgent.getMediaBuyDelivery({
account: { account_id: 'acc_acme_pinnacle' },
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} campaigns for account`);
console.log(`Total spend: $${validated.aggregated_totals.spend.toFixed(2)}`);
```
```python Python test=false theme={null}
import asyncio
from adcp.testing import test_agent
from adcp.types import GetMediaBuyDeliveryRequest
async def main():
# Get delivery for a specific advertiser account
result = await test_agent.get_media_buy_delivery(
GetMediaBuyDeliveryRequest(
account={'account_id': 'acc_acme_pinnacle'},
status_filter='active',
start_date='2024-02-01',
end_date='2024-02-07'
)
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Query failed: {result.errors}")
print(f"{result.aggregated_totals.media_buy_count} campaigns for account")
print(f"Total spend: ${result.aggregated_totals.spend:.2f}")
asyncio.run(main())
```
## メトリクスの定義
| Metric | Definition |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Impressions** | 広告が表示された回数 |
| **Spend** | 指定通貨での支出額 |
| **Clicks** | 広告クリック数（利用可能な場合） |
| **CTR** | クリック率 (clicks/impressions) |
| **Views** | 課金対象の視聴閾値でのコンテンツエンゲージメント——動画視聴、オーディオ/ポッドキャストのストリーム開始、またはフォーマット固有の視聴イベント |
| **Completed Views** | オーディオ/動画の完了（閾値または 100%） |
| **Completion Rate** | 完了率 (completed\_views/impressions) |
| **Conversions** | 帰属コンバージョン（購入、新規リスナー、アプリインストールなど） |
| **Conversion Value** | 帰属コンバージョンの総金銭的価値 |
| **ROAS** | 広告費用対効果 (conversion\_value / spend) |
| **New-to-Brand Rate** | 初回購入者によるコンバージョンの割合 (0-1) |
| **Cost per Acquisition** | コンバージョンあたりコスト (spend / conversions) |
| **Reach** | リーチしたユニークユーザー数（計測単位は `reach_unit` を参照: individuals, households, devices, accounts, cookies）。計測ウィンドウは `reach_window` で宣言。それがない場合、バイヤーは行をまたいでリーチを合計してはなりません。 |
| **Reach Unit** | リーチの計測単位——reach が存在する場合は必須 |
| **Reach Window** | 報告されるリーチ/フリークエンシーのウィンドウ意味論: `cumulative`（キャンペーン開始以降のユニーク）、`period`（重複しない単一レポート期間内のユニーク——例: 日次スナップショット）、`rolling`（後方ウィンドウ内のユニーク——例: 直近 7 日）。行をまたいで合計しないこと。任意だが、reach が存在する場合は強く推奨。 |
| **Frequency** | `reach_window` にわたって計測された、リーチ単位あたりの平均広告接触回数 |
| **Viewability** | `vendor`、`measurable_impressions`（分母）、`viewable_impressions`、`viewable_rate`、`viewed_seconds`（計測可能インプレッションあたりの平均インビュー時間——`viewed_seconds` 最適化目標と対）、`standard` を持つオブジェクト |
| **Follows** | 配信に帰属する新規フォロワー、ページのいいね、無料のチャンネル/フィード購読 |
| **Pacing Index** | 実績 vs 期待の配信速度 (1.0 = 計画通り、\<1.0 = 遅れ、>1.0 = 先行) |
| **CPM** | インプレッション 1,000 件あたりのコスト (spend/impressions \* 1000) |
## クエリの挙動
### コンテキストベースのクエリ
* `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 時間の遅延があります
* リアルタイムのインプレッションカウントは提供されない
* ライブモニタリングではなく、定期レポートや最適化判断に利用します
**段階的成熟のチャネル**: 課金グレードのデータが初日に最終値として届くのではなく段階的に生成されるチャネルでは、データ鮮度が異なります——放送 TV（Live → C3 → C7 の DVR 累積、最終 C7 は放送後約 15〜22 日）、DOOH（暫定の再生 → IVT/不正チェック後の最終）、IVT フィルタリング付きデジタル（raw → post-GIVT → post-SIVT）、ポッドキャスト（7 日 → 30 日ダウンロード）。`reporting_capabilities.measurement_windows` を持つプロダクトがこれらのタイムラインを宣言します。バイヤーは、合意された条件の `billing_measurement` で指定された `measurement_window` に対して照合します。計測条件は [Accountability](/docs/media-buy/advanced-topics/accountability) を、ライフサイクル全体は[最適化とレポーティング](/docs/media-buy/media-buys/optimization-reporting)を参照してください。
## エラーハンドリング
| Error Code | Description | Resolution |
| -------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_MISSING` | No credentials presented | Provide credentials via auth header |
| `AUTH_INVALID` | Credentials rejected (expired / revoked) | Human credential rotation required; do not auto-retry |
| `MEDIA_BUY_NOT_FOUND` | Media buy doesn't exist | Verify `media_buy_id`; for legacy correlation use `get_media_buys` + `context.internal_campaign_id` |
| `INVALID_DATE_RANGE` | Invalid start/end dates | Use YYYY-MM-DD format, ensure start \< end |
| `DATE_RANGE_NOT_SUPPORTED` | Product only supports lifetime reporting | Omit `start_date` and `end_date`. Check `reporting_capabilities.date_range_support` on the product. |
| `UNSUPPORTED_GRANULARITY` | Requested `time_granularity` is not in the product's `windowed_pull_granularities` | Re-issue with a granularity from `error.details.supported_granularities`, or omit `time_granularity` to fall back to cumulative date-range pulls. See [Windowed pull recovery](#windowed-pull-recovery). |
| `CONTEXT_REQUIRED` | No media buys in context | Provide media\_buy\_ids explicitly |
| `INVALID_STATUS_FILTER` | Invalid status value | Use valid status: pending\_creatives, pending\_start, active, paused, completed |
## パッケージレベルのメトリクス
`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 など)
**Accountability**:
* **`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 など）
```json theme={null}
{
"by_package": [
{
"package_id": "pkg_001",
"spend": 5000,
"impressions": 100000,
"pricing_model": "cpm",
"rate": 50,
"currency": "USD",
"delivery_status": "delivering",
"by_creative": [
{
"creative_id": "hero_video_30s",
"weight": 60,
"impressions": 60000,
"spend": 3000,
"clicks": 3000,
"ctr": 0.05,
"completion_rate": 0.72
},
{
"creative_id": "hero_video_15s",
"weight": 40,
"impressions": 40000,
"spend": 2000,
"clicks": 1200,
"ctr": 0.03,
"completion_rate": 0.85
}
]
}
]
}
```
バリアントレベルの配信データ（アセットの組み合わせ最適化、生成クリエイティブ）を含むより深いクリエイティブ分析には、[`get_creative_delivery`](/docs/creative/task-reference/get_creative_delivery) を使います。これはクリエイティブプロトコルのタスクです——クリエイティブプロトコルを実装する任意のエージェントで呼び出せます。`supported_protocols` に `"creative"` を宣言していれば、同じセラーエージェントであってもよい。[セラーエージェントのクリエイティブ機能](/docs/creative/sales-agent-creative-capabilities)を参照してください。
## カタログアイテムのレポート
カタログ駆動のパッケージ（`catalog` フィールドを持つパッケージ）では、セラーは各パッケージ内の `by_catalog_item` 配列でカタログアイテムごとの配信を返せます。
各エントリはカタログアイテムを識別し、標準の配信メトリクスを含みます:
| Field | Description |
| ----------------- | --------------------------------------------------------------------- |
| `content_id` | アイテム識別子（SKU、GTIN、求人 ID など） |
| `content_id_type` | 識別子の型（`sku`、`gtin`、`job_id` など）。カタログの `content_id_type` に一致 |
| Standard metrics | `impressions`、`spend`、`clicks`、`ctr`、`conversions`、`roas`、その他の配信メトリクス |
これは任意です。アイテムレベルのレポートをサポートするセラーは `by_catalog_item` を埋め、しないセラーは単に省略します。
```json theme={null}
{
"by_package": [
{
"package_id": "pkg_001",
"spend": 5000,
"impressions": 100000,
"pricing_model": "cpc",
"rate": 1.20,
"currency": "USD",
"delivery_status": "delivering",
"by_catalog_item": [
{
"content_id": "SKU-12345",
"content_id_type": "sku",
"impressions": 45000,
"spend": 2250,
"clicks": 1800,
"ctr": 0.04,
"conversions": 90,
"roas": 4.2
},
{
"content_id": "SKU-67890",
"content_id_type": "sku",
"impressions": 55000,
"spend": 2750,
"clicks": 2200,
"ctr": 0.04,
"conversions": 110,
"roas": 3.8
}
]
}
]
}
```
## ウィンドウ化プル復旧
`reporting_webhook` はバイヤーが選んだ `reporting_frequency`（hourly、daily、monthly）で発火します。受信側がトランスポートのリトライが尽きるほど長くオフラインだった場合、GET が同じスライスを再現できない限り、バイヤーはウィンドウごとの詳細を失います。`time_granularity` + `include_window_breakdown` がそのギャップを埋めます。
### ケイパビリティの確認
セラーは、プル復旧で honor する粒度を `reporting_capabilities.windowed_pull_granularities` で宣言します。バイヤーは `time_granularity` を要求する前にケイパビリティを確認しなければなりません（MUST）:
```json test=false theme={null}
{
"reporting_capabilities": {
"available_reporting_frequencies": ["hourly", "daily"],
"windowed_pull_granularities": ["daily"]
}
}
```
この例のセラーは hourly の Webhook を出しますが、プルは daily のみ honor します——Webhook が Kafka のタップで、履歴のプルはウェアハウスを通るストリームタップのアーキテクチャで一般的です。二経路のパリティは**宣言された**集合で成立します。hourly の復旧では Webhook が主です。完全なパリティを望むセラーは、発火するすべての頻度を宣言します。
### ウィンドウ化スライスの要求
```json test=false theme={null}
{
"media_buy_ids": ["mb_12345"],
"start_date": "2026-06-01",
"end_date": "2026-06-02",
"time_granularity": "hourly",
"include_window_breakdown": true
}
```
### レスポンスの形状
各メディアバイはレスポンスに `windows[]` 配列を得ます:
```json test=false theme={null}
{
"media_buy_deliveries": [
{
"media_buy_id": "mb_12345",
"status": "active",
"totals": { "impressions": 12345678, "spend": 5432.10 },
"by_package": [ /* cumulative per-package — unchanged */ ],
"windows": [
{
"window_start": "2026-06-01T00:00:00Z",
"window_end": "2026-06-01T01:00:00Z",
"totals": { "impressions": 510234, "spend": 226.05 },
"by_package": [
{ "package_id": "pkg_001", "impressions": 510234, "spend": 226.05 }
],
"is_final": true
},
{
"window_start": "2026-06-01T01:00:00Z",
"window_end": "2026-06-01T02:00:00Z",
"totals": { "impressions": 488112, "spend": 215.83 },
"is_final": true
}
]
}
]
}
```
スライスは `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 発火のペイロードを反映するため、バイヤーの照合パイプラインはトランスポート経路で分岐しません。
このサーフェスは、データを運ぶイベントについて [snapshot-and-log](/docs/protocol/snapshot-and-log) のルール 4（どちらの経路も完全）を支えます。より広い契約はそのページを参照してください。
## ディメンション別内訳
リクエストに `reporting_dimensions` を含めると、レスポンスは各 `by_package` エントリ内にディメンション別内訳の配列を含みます。各内訳エントリは `delivery-metrics` のすべてのフィールドに加え、ディメンション固有の識別子を継承します。
### 内訳の要求
```json test=false theme={null}
{
"media_buy_ids": ["mb_123"],
"reporting_dimensions": {
"geo": { "geo_level": "metro", "system": "nielsen_dma", "limit": 10 },
"device_type": {},
"placement": { "limit": 5, "sort_by": "roas" }
}
}
```
各ディメンションは任意の `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）はサポートされません。
### 利用可能なディメンション
| Dimension | Breakdown field | Required fields | Additional fields | Capability declaration |
| --------------- | -------------------- | -------------------------------------------------------- | ------------------------------------ | ------------------------------------ |
| Geography | `by_geo` | `geo_level`, `geo_code`, `impressions`, `spend` | `system`, `country`, `geo_name` | `supports_geo_breakdown` |
| Device type | `by_device_type` | `device_type`, `impressions`, `spend` | — | `supports_device_type_breakdown` |
| Device platform | `by_device_platform` | `device_platform`, `impressions`, `spend` | — | `supports_device_platform_breakdown` |
| Audience | `by_audience` | `audience_id`, `audience_source`, `impressions`, `spend` | `audience_name` | `supports_audience_breakdown` |
| Placement | `by_placement` | `placement_id`, `impressions`, `spend` | `publisher_domain`, `placement_name` | `supports_placement_breakdown` |
どのディメンションが利用可能かはプロダクトの `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` フィールドは、オーディエンスセグメントがどこに由来するかを示します:
| Source | Description | Targetable? |
| ------------- | ------------------------------------- | --------------------------------------------- |
| `synced` | `sync_audiences` によるバイヤーのファーストパーティデータ | はい——`audience_include`/`audience_exclude` を使用 |
| `platform` | セラーのネイティブセグメント（興味、行動） | いいえ——情報提供 |
| `third_party` | 外部データプロバイダーのセグメント | いいえ——情報提供 |
| `lookalike` | シードからのプラットフォーム生成の拡張 | いいえ——情報提供 |
| `retargeting` | セラーのピクセル/タグによる過去のエンゲージメント | いいえ——情報提供 |
| `unknown` | 未分類または認識されないオーディエンスソース | いいえ——情報提供 |
## ベストプラクティス
**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. ステータス変化を追跡する**
複数ステータスのクエリで、キャンペーンが停止/完了した理由を把握します。
## 配信後のガバナンス検証
配信レポートは最後のステップではありません。キャンペーンガバナンスが有効な場合、配信データはガバナンス検証に流れ込み、認可されていないサプライパス、ジオのドリフト、ペーシング違反を検出します。
ガバナンスのフィードバックループ:
1. `get_media_buy_delivery` で配信データを取得
2. [`report_plan_outcome`](/docs/governance/campaign/tasks/report_plan_outcome) でガバナンスエージェントに結果を報告
3. ガバナンスエージェントが実際の配信を計画パラメータと比較（ドリフト検出）
4. [`validate_property_delivery`](/docs/governance/property/tasks/validate_property_delivery) でプロパティの配信を検証し、認可されていないサプライパスを検出
| Governance task | Purpose |
| ------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| [`report_plan_outcome`](/docs/governance/campaign/tasks/report_plan_outcome) | 予算追跡とドリフト検出のためにガバナンスエージェントへ配信データを供給 |
| [`validate_property_delivery`](/docs/governance/property/tasks/validate_property_delivery) | 配信記録をプロパティリストに対して検証——認可されていないプロパティで配信されている広告を検出 |
| [`validate_content_delivery`](/docs/governance/content-standards/tasks/validate_content_delivery) | コンテンツアーティファクトをブランド適合性の標準に対して検証 |
| [`get_plan_audit_logs`](/docs/governance/campaign/tasks/get_plan_audit_logs) | 完全なプラン状態と監査証跡を表示 |
このフィードバックループがなければ、配信データは報告されても検証されません。予算超過、ペーシングの乖離、ジオのドリフト、認可されていないサプライパスが検出されないままになります。
## 次のステップ
配信データ取得後にできること:
1. **キャンペーンを最適化**: [`update_media_buy`](/docs/media-buy/task-reference/update_media_buy) で予算、ペーシング、ターゲティングを調整
2. **フィードバックを共有**: [`provide_performance_feedback`](/docs/media-buy/task-reference/provide_performance_feedback) で結果をセラーに共有
3. **クリエイティブを更新**: ライブラリ対応のセラーには [`sync_creatives`](/docs/creative/task-reference/sync_creatives) を、インライン専用のセラーには [`update_media_buy`](/docs/media-buy/task-reference/update_media_buy) のインライン `packages[].creatives` を使用
4. **フォローアップキャンペーンを作成**: インサイトに基づき [`create_media_buy`](/docs/media-buy/task-reference/create_media_buy) を実行
## さらに学ぶ
* [Media Buy Lifecycle](/docs/media-buy/media-buys/) - キャンペーンワークフロー全体
* [Async Operations](/docs/building/by-layer/L3/async-operations) - 非同期パターンとステータス処理
* [Performance Optimization](/docs/media-buy/media-buys/optimization-reporting) - 配信データを用いた最適化