> ## 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_creative_delivery > get_creative_delivery は AdCP でジェネレーティブおよびスタティッククリエイティブのマニフェストとパフォーマンスメトリクスを含むバリアントレベルの配信データを取得します。 マニフェストとメトリクスを含むバリアントレベルの内訳を持つクリエイティブ配信データを取得します。このタスクは、クリエイティブからどんなバリアントが作成されたか、それらがどのように見えたか（マニフェスト経由）、そしてどのようなパフォーマンスを発揮したかを返します。 これはクリエイティブプロトコルのタスクです。`supported_protocols` に `"creative"` を宣言し、[クリエイティブエージェントのケイパビリティ](#ケイパビリティ宣言)に `"delivery"` を持つすべてのエージェントで呼び出す — 専用のクリエイティブサービスであっても[クリエイティブプロトコルを実装するセールスエージェント](/docs/creative/sales-agent-creative-capabilities)であっても同じです。 **リクエストスキーマ**: [`/schemas/v3/creative/get-creative-delivery-request.json`](https://adcontextprotocol.org/schemas/v3/creative/get-creative-delivery-request.json) **レスポンススキーマ**: [`/schemas/v3/creative/get-creative-delivery-response.json`](https://adcontextprotocol.org/schemas/v3/creative/get-creative-delivery-response.json) ## リクエストパラメータ スコーピングフィルター（`media_buy_ids` または `creative_ids`）のうち少なくとも1つが必須です。 | パラメータ | タイプ | 必須 | 説明 | | --------------- | -------------------------------------------------------------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------- | | `account` | [account-ref](/docs/building/by-layer/L2/accounts-and-agents#account-references) | No | アカウント参照。セラーが暗黙的解決をサポートする場合、`{ "account_id": "..." }` または `{ "brand": {...}, "operator": "..." }` を渡します。結果をこのアカウント内のクリエイティブに限定します。 | | `media_buy_ids` | string\[] | Yes\* | パブリッシャー ID で特定のメディアバイにフィルタリング | | `creative_ids` | string\[] | Yes\* | ID で特定のクリエイティブにフィルタリング | | `start_date` | string | No | 配信期間の開始日（YYYY-MM-DD、プラットフォームのレポートタイムゾーンで解釈） | | `end_date` | string | No | 配信期間の終了日（YYYY-MM-DD、プラットフォームのレポートタイムゾーンで解釈） | | `max_variants` | integer | No | クリエイティブあたりの返却バリアント数の最大値。バリアント数の多いジェネレーティブクリエイティブに有用。 | | `pagination` | object | No | クリエイティブ配列のカーソルベースのページネーションパラメータ（`max_results`、`cursor`）。省略した場合、すべての一致するクリエイティブが返されます。 | \* `media_buy_ids` または `creative_ids` のうち少なくとも1つが必要。 ## レスポンス | フィールド | 説明 | | ------------------ | ------------------------------------------------------------------------------------- | | `account_id` | アカウント識別子（特定のアカウントにスコープされた場合に存在） | | `media_buy_id` | セラーのメディアバイ識別子（リクエストが単一のバイにスコープされた場合に存在） | | `currency` | 金額の ISO 4217 通貨コード（例: 'USD'、'EUR'） | | `reporting_period` | 開始/終了タイムスタンプと `timezone`（IANA 識別子 — プラットフォームはネイティブタイムゾーンでレポートします）を持つ日付範囲 | | `creatives` | バリアント内訳を持つクリエイティブ配信データの配列 | | `pagination` | （オプション）`max_results`、`cursor`、`has_more` を持つページネーション情報。リクエストにページネーションパラメータが含まれた場合に存在。 | ### クリエイティブオブジェクト | フィールド | 説明 | | --------------- | ------------------------------------------------------------ | | `creative_id` | クリエイティブ識別子 | | `media_buy_id` | セラーのメディアバイ識別子（リクエストが複数のメディアバイにまたがった場合に存在） | | `format_id` | このクリエイティブのフォーマット | | `totals` | すべてのバリアントにわたる集計配信メトリクス — 下記の[配信メトリクスフィールド](#配信メトリクスフィールド)を参照 | | `variant_count` | バリアントの総数（`max_variants` 使用時は `variants` 配列の長さを超える場合があります） | | `variants` | バリアントレベルの配信データの配列（クリエイティブにまだバリアントがない場合は空） | ### 配信メトリクスフィールド `creative.totals` と各 `variant` エントリの両方で利用可能なフィールド。よく使われるサブセット——インクリメンタリティ、ブランドリフト、放送のメトリクスを含む完全なリストについては[配信メトリクススキーマ](https://adcontextprotocol.org/schemas/v3/core/delivery-metrics.json)を参照。 | フィールド | 説明 | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `impressions` | 配信されたインプレッション | | `spend` | 使われた金額（`currency` 単位） | | `clicks` | 総クリック数 | | `ctr` | クリック率（clicks/impressions） | | `cpm` | 1000 インプレッションあたりのコスト（(spend/impressions) × 1000） | | `cost_per_click` | クリックあたりのコスト（spend/clicks） | | `views` | 課金対象のビュー——しきい値はフォーマットと価格モデルによって異なる | | `completed_views` | 動画/音声の完了 | | `completion_rate` | 完了率（completed\_views/impressions）。該当しない場合（例: 非動画のバイ）は `null` | | `quartile_data` | 音声/動画の四分位完了データ——`q1_views`、`q2_views`、`q3_views`、`q4_views` を持つオブジェクト。該当しない場合（例: 非動画のバイ）は `null` | | `reach` | `reach_unit` で指定された単位でのユニークリーチ。計測ウィンドウは `reach_window` で宣言。それがなければ行をまたいで合計しないこと | | `reach_unit` | `reach` の計測単位。`reach` が存在するときは必須 | | `reach_window` | リーチ/フリークエンシーのウィンドウのセマンティクス——`kind`（キャンペーン開始以降のユニークには `cumulative`、非重複のスナップショットには `period`、末尾ウィンドウには `rolling`）と `period`（Duration、`period` と `rolling` で必須）を持つオブジェクト。任意だが、`reach` が存在するときは常に強く推奨 | | `frequency` | `reach_window` にわたって計測された `reach_unit` あたりの平均フリークエンシー | | `grps` | 配信された Gross Rating Points（CPP 向け） | | `conversions` | 総アトリビューションコンバージョン。存在するときは `by_event_type[].count` の合計に等しい | | `conversion_value` | アトリビューションコンバージョンの総金額 | | `roas` | 広告費用対効果（conversion\_value/spend）——下記の注記を参照 | | `cost_per_acquisition` | コンバージョンあたりのコスト（spend/conversions）——下記の注記を参照 | | `new_to_brand_rate` | 初回ブランド購入者からのコンバージョンの割合（0〜1） | | `leads` | 生成されたリード（`event_type='lead'` の `by_event_type` の便宜的エイリアス） | | `by_event_type` | イベントタイプ別のコンバージョン——`{ event_type, count, value?, event_source_id? }` の配列 | | `by_action_source` | アクションソース別のコンバージョン（website、app、in\_store）——`{ action_source, count, value?, event_source_id? }` の配列 | | `dooh_metrics` | DOOH 固有のデータ——`loop_plays`、`screens_used`、`screen_time_seconds`、`sov_achieved`、`venue_breakdown` を持つオブジェクト | | `viewability` | ビューアビリティデータ——`vendor`、`measurable_impressions`、`viewable_impressions`、`viewable_rate`、`viewed_seconds`（計測可能インプレッションあたりの平均インビュー時間——`viewed_seconds` 最適化ゴールと対になる）、`standard` を持つオブジェクト。計測されたビューアビリティ値がレポートされるときは常に `standard` が存在すべき（SHOULD） | | `engagements` | 視聴を超える総広告エンゲージメント（プラットフォーム固有） | | `follows` | 配信に起因する新規フォロワーまたは購読 | | `saves` | 配信に起因する保存、ブックマーク、ピン | | `profile_visits` | 配信に起因するプラットフォーム内ページ訪問 | | `engagement_rate` | プラットフォーム固有のエンゲージメント率（engagements/impressions） | | `vendor_metric_values` | ベンダー実証のメトリクス（ビューアビリティ、アテンションなど）——ベンダーとメトリクス識別子ごとに 1 エントリ | > **支出由来のメトリクス。** セラーは、個々の `variant` オブジェクトに `roas` と `cost_per_acquisition` を埋めるべきではありません——支出はクリエイティブ全体に適用されるため、バリアントごとに帰属できません。これらのフィールドは `creative.totals` でのみ意味を持ちます。`by_event_type` エントリはイベントタイプごとに `count` と `value` を運びますが、支出由来のレートは運びません。 > **プラットフォーム条件付きフィールド。** `dooh_metrics` は DOOH キャンペーンでのみ存在します。エンゲージメントフィールド（`engagements`、`follows`、`saves`、`profile_visits`、`engagement_rate`）はプラットフォーム固有です。すべてのセラーが標準化されたフィールドでそれらを出力するわけではありません——代わりにエンゲージメントデータに `variant.ext` を使うものもあります。 ### バリアントオブジェクト 各バリアントは特定の実行を表します: 固定クリエイティブ（Tier 1）、プラットフォームが選択したアセットの組み合わせ（Tier 2）、または生成されたバリアント（Tier 3）。カタログ駆動パッケージでは、個別の広告実行としてレンダリングされた各カタログアイテムがバリアントになる — バリアントのマニフェストにはレンダリングされた特定のアイテムを含むカタログ参照が含まれます。 | フィールド | 説明 | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `variant_id` | プラットフォームが割り当てたバリアント識別子 | | `manifest` | （オプション）レンダリングされたクリエイティブマニフェスト — 入力アセットではなく実際に配信された出力。format\_id と解決済みアセットを含みます。すべてのプラットフォームがすべてのバリアントのマニフェストを提供できるわけではありません。 | | `generation_context` | （オプション、Tier 3）生成をトリガーした入力シグナル — 例: ページトピック、会話テーマ、クエリカテゴリ。プラットフォームは生のユーザー入力ではなく、要約/匿名化されたシグナルを提供します。コンテンツコンテキストが AdCP コンテンツ標準を通じて管理される場合、特定のコンテンツアーティファクトにリンクする `artifact` 参照を含みます。ベンダー固有のコンテキスト構造のために `ext` をサポートします。 | | `ext` | （オプション）プラットフォーム固有のデータ。ソーシャルプラットフォームはプラットフォームごとに異なるエンゲージメントメトリクス（アップボート、コメント、シェア）にこれを使用します。 | | 標準メトリクス | すべての[配信メトリクスフィールド](#配信メトリクスフィールド)——`creative.totals` と同じ形状 | `creative_id` と `variant_id` は別個の名前空間です。正準的なビルドからデリバリーへの結合は `build_creative.variants[].build_variant_id` → プロモートされた `creative_id` → デリバリーの `creative_id` です。`variant_id` は、プラットフォームが配信した実行バリアント id のままです。 `ctr`、`completion_rate`、`roas`、`cost_per_click` などの派生メトリクスはプラットフォームが計算したものであり、丸め、アトリビューションウィンドウ、またはフィルタリングされたインプレッションにより、構成要素の単純な除算と等しくない場合があります。 ## Tier の動作 ### Tier 1: 標準クリエイティブ 1つのクリエイティブが1つのバリアントに1対1でマッピングされます。バリアントのメトリクスはクリエイティブのトータルと一致します。 ```json theme={null} { "media_buy_id": "mb_12345", "currency": "USD", "reporting_period": { "start": "2026-01-20T00:00:00-05:00", "end": "2026-01-27T23:59:59-05:00", "timezone": "America/New_York" }, "creatives": [ { "creative_id": "hero_video_30s", "totals": { "impressions": 150000, "spend": 7500, "clicks": 4500, "ctr": 0.03, "completion_rate": 0.72 }, "variants": [ { "variant_id": "hero_video_30s", "impressions": 150000, "spend": 7500, "clicks": 4500, "ctr": 0.03, "completion_rate": 0.72 } ] } ] } ``` ### プラットフォームエンゲージメントメトリクス ソーシャルおよびフィードネイティブプラットフォームは、エンゲージメントタイプがプラットフォームごとに異なるため、各バリアントの `ext` フィールドにエンゲージメントデータを含める: ```json theme={null} { "variant_id": "promoted_post_running_community", "impressions": 85000, "spend": 4250, "clicks": 2550, "ctr": 0.03, "ext": { "upvotes": 1240, "comments": 87, "shares": 34, "saves": 156, "comment_sentiment": "positive" } } ``` `ext` フィールドはプラットフォーム間で標準化されていない — 各プラットフォームが独自のエンゲージメントスキーマを定義します。複数のソーシャルプラットフォームにわたって集計するバイヤーはプラットフォーム固有のフィールドを共通モデルにマッピングすべきです。 ### Tier 2: アセットグループ最適化 バイヤーが `selection_mode: "optimize"` を持つフォーマットを使用して複数のアセット代替案を提供します。プラットフォームが組み合わせをテストし、どのアセットが選択されたかを示すマニフェストと共に各バリアントを返します。 ```json theme={null} { "media_buy_id": "mb_12345", "currency": "USD", "reporting_period": { "start": "2026-01-20T00:00:00-05:00", "end": "2026-01-27T23:59:59-05:00", "timezone": "America/New_York" }, "creatives": [ { "creative_id": "summer_campaign_assets", "totals": { "impressions": 200000, "spend": 10000, "clicks": 8000, "ctr": 0.04 }, "variants": [ { "variant_id": "var_headline_a_image_c", "manifest": { "format_id": { "agent_url": "https://creative.example.com", "id": "display_300x250" }, "assets": { "headline_0_text": { "asset_type": "text", "content": "Summer Sale - 50% Off" }, "image_0_url": { "asset_type": "image", "url": "https://cdn.brand.com/beach_hero.jpg", "width": 300, "height": 250 } } }, "impressions": 120000, "spend": 6000, "clicks": 6000, "ctr": 0.05 }, { "variant_id": "var_headline_b_image_d", "manifest": { "format_id": { "agent_url": "https://creative.example.com", "id": "display_300x250" }, "assets": { "headline_0_text": { "asset_type": "text", "content": "Shop Summer Styles" }, "image_0_url": { "asset_type": "image", "url": "https://cdn.brand.com/sunset_hero.jpg", "width": 300, "height": 250 } } }, "impressions": 80000, "spend": 4000, "clicks": 2000, "ctr": 0.025 } ] } ] } ``` ### Tier 3: ジェネレーティブクリエイティブ プラットフォームがブランドマニフェストと入力コンテキストからバリアントを生成します。`manifest` には生成されたアセットが含まれる — バイヤーが提出したものとは完全に異なる場合があります。 パブリッシャーが AdCP コンテンツ標準を使用する場合、`generation_context` に特定のコンテンツ（記事、動画など）にバリアントをリンクする `artifact` 参照を含めることができます。プラットフォームはベンダー固有のコンテキスト構造のために `ext` を使用することもできます。 ```json theme={null} { "media_buy_id": "mb_12345", "currency": "USD", "reporting_period": { "start": "2026-01-20T00:00:00-05:00", "end": "2026-01-27T23:59:59-05:00", "timezone": "America/New_York" }, "creatives": [ { "creative_id": "generative_banner", "totals": { "impressions": 300000, "spend": 15000, "clicks": 12000, "ctr": 0.04 }, "variants": [ { "variant_id": "gen_mobile_morning", "generation_context": { "context_type": "web_page", "artifact": { "property_id": { "type": "domain", "value": "techreview.example.com" }, "artifact_id": "article_semiconductor_trends_2026" }, "topic": "technology, semiconductors", "device_class": "mobile" }, "manifest": { "format_id": { "agent_url": "https://creative.example.com", "id": "display_300x250_generative" }, "assets": { "hero_image": { "asset_type": "image", "url": "https://cdn.creative.example.com/generated/mobile_morning_v1.jpg", "width": 300, "height": 250 }, "headline": { "asset_type": "text", "content": "Start Your Summer Right" } } }, "impressions": 180000, "spend": 9000, "clicks": 9000, "ctr": 0.05 }, { "variant_id": "gen_desktop_evening", "generation_context": { "context_type": "web_page", "topic": "lifestyle, evening entertainment", "device_class": "desktop" }, "manifest": { "format_id": { "agent_url": "https://creative.example.com", "id": "display_728x90_generative" }, "assets": { "hero_image": { "asset_type": "image", "url": "https://cdn.creative.example.com/generated/desktop_evening_v1.jpg", "width": 728, "height": 90 }, "headline": { "asset_type": "text", "content": "Evening Deals Await" } } }, "impressions": 120000, "spend": 6000, "clicks": 3000, "ctr": 0.025 } ] } ] } ``` ## バリアントのプレビュー `request_type: "variant"` を指定して `preview_creative` を使用し、特定のバリアントが配信時にどのように見えたかを確認します: ```json theme={null} { "request_type": "variant", "variant_id": "gen_mobile_morning" } ``` 各バリアントには完全な `manifest` が含まれているため、そのマニフェストを直接 `preview_creative` に渡して標準的な単一リクエストとして再レンダリングすることもできます。 ## 配信レポートとの関係 | タスク | プロトコル | 提供する情報 | | ------------------------ | ------- | ------------------------------------------------------------------ | | `get_media_buy_delivery` | メディアバイ | WHERE と HOW MUCH: インプレッション、スペンド、プレースメントデータ、オプションの `by_creative` 内訳 | | `get_creative_delivery` | クリエイティブ | WHAT RAN と HOW: バリアントマニフェストとバリアントレベルのメトリクス | 両方のレスポンスにわたってデータを相関させるために `media_buy_id` + `creative_id` を結合キーとして使用します。 セールスエージェントが両方のプロトコルを実装する場合、両方のタスクが同じエージェント URL で利用可能です。完全なパターンは[セールスエージェントのクリエイティブ機能](/docs/creative/sales-agent-creative-capabilities)を参照。 ## クロスエージェント集計 複数のセラーにわたってキャンペーンを実施する場合、各エージェントで `get_creative_delivery` を個別に呼び出して結果を相関させる: * **結合キー**: バイヤーが割り当てた `creative_id` を使用してエージェント間で同じクリエイティブを相関させる。アップロード時に `concept_id` を使用した場合、コンセプトでフィルタリングして関連するクリエイティブをグループ化します。 * **`variant_id` のスコープ**: バリアント ID はエージェントとクリエイティブ内で一意であり、グローバルには一意ではありません。2つのエージェントが同じ `variant_id` 値を持つバリアントを生成する場合があります。集計ダッシュボードを構築する際はエージェント URL でプレフィックスを付ける。 * **タイムゾーン処理**: 各エージェントは `reporting_period.timezone` を通じて独自のタイムゾーンでレポートする可能性があります。メトリクスを集計する前に共通のタイムゾーンに正規化します。 * **`max_variants` の選択**: エージェントは `max_variants` が結果セットを制限する場合に返すバリアントを選択します。ほとんどのエージェントはインプレッション量（最も多く配信されたものが先）で優先度を付ける。代表的なサンプリングのためには、単一の大きな `max_variants` 値に頼るのではなく、異なる時間範囲で複数の呼び出しを行います。 ## クロスエージェントダッシュボードの構築 複数のエージェントからの配信データを統合ビューに集計する場合、以下の手順に従う: 1. **収集**: 同じ `creative_ids` フィルターを使用して、各エージェントで `get_creative_delivery` を並列に呼び出す。 2. **タイムゾーンの正規化**: 合計する前に各エージェントの `reporting_period` を共通のタイムゾーンに変換します。 3. **`creative_id` でマージ**: エージェント間で `creative_id` によって結果をグループ化します。`totals`（impressions、spend、clicks）を合計します。`ctr` などの派生メトリクスは平均しない — 合計されたコンポーネントから再計算します。 4. **`variant_id` にプレフィックス**: `agent_url + variant_id` を組み合わせてグローバルに一意なバリアントキーを作成する（例: `https://sales.pinnaclemedia-example.com/var_a1b2c3`）。これにより、2つのエージェントが独立して同じバリアント ID を割り当てた場合の衝突を防ぐ。 5. **`concept_id` でグループ化**: キャンペーンレベルのロールアップのために、`concept_id` を使用してサイズとセラーにわたる関連クリエイティブをグループ化します。コンセプトからクリエイティブへのマッピングは各エージェントの `list_creatives` から取得します。 ```javascript theme={null} // 疑似コード: 3つのセラーから配信を集計 const agents = [pinnacle, novaSports, streamhaus]; const results = await Promise.all( agents.map(agent => agent.getCreativeDelivery({ creative_ids: ['acme_holiday_300x250'], start_date: '2026-11-01', end_date: '2026-11-15', }) ) ); const merged = {}; for (const [i, result] of results.entries()) { if (result.errors) continue; // 失敗したエージェントをスキップ、後でリトライ for (const creative of result.creatives) { const key = creative.creative_id; if (!merged[key]) merged[key] = { impressions: 0, spend: 0, clicks: 0, variants: [] }; merged[key].impressions += creative.totals.impressions; merged[key].spend += creative.totals.spend; merged[key].clicks += creative.totals.clicks || 0; for (const v of creative.variants || []) { merged[key].variants.push({ ...v, variant_id: `${agents[i].url}/${v.variant_id}`, // グローバルに一意 }); } } } // 派生メトリクスを再計算 for (const c of Object.values(merged)) { c.ctr = c.impressions > 0 ? c.clicks / c.impressions : 0; } ``` ## ケイパビリティ宣言 このタスクをサポートするエージェントは `list_creative_formats` レスポンスの `capabilities` 配列に `"delivery"` を宣言する: ```json theme={null} { "creative_agents": [{ "agent_url": "https://ads.seller-example.com", "capabilities": ["validation", "assembly", "preview", "delivery"] }] } ``` バイヤーはこれを `list_creative_formats` を呼び出してケイパビリティに `"delivery"` を持つエージェントの `creative_agents` 配列を確認することで発見します。これはセールスエージェントを含む、クリエイティブプロトコルを実装するすべてのエージェントに適用されます。