AdCP — get_creative

マニフェストとメトリクスを含むバリアントレベルの内訳を持つクリエイティブ配信データを取得します。このタスクは、クリエイティブからどんなバリアントが作成されたか、それらがどのように見えたか（マニフェスト経由）、そしてどのようなパフォーマンスを発揮したかを返します。これはクリエイティブプロトコルのタスクです。supported_protocols に "creative" を宣言し、クリエイティブエージェントのケイパビリティに "delivery" を持つすべてのエージェントで呼び出す — 専用のクリエイティブサービスであってもクリエイティブプロトコルを実装するセールスエージェントであっても同じです。 リクエストスキーマ: /schemas/v3/creative/get-creative-delivery-request.json レスポンススキーマ: /schemas/v3/creative/get-creative-delivery-response.json

リクエストパラメータ

スコーピングフィルター（media_buy_ids または creative_ids）のうち少なくとも1つが必須です。

パラメータ	タイプ	必須	説明
`account`	account-ref	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 エントリの両方で利用可能なフィールド。よく使われるサブセット——インクリメンタリティ、ブランドリフト、放送のメトリクスを含む完全なリストについては配信メトリクススキーマを参照。

フィールド	説明
`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でマッピングされます。バリアントのメトリクスはクリエイティブのトータルと一致します。

{
  "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 フィールドにエンゲージメントデータを含める:

{
  "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" を持つフォーマットを使用して複数のアセット代替案を提供します。プラットフォームが組み合わせをテストし、どのアセットが選択されたかを示すマニフェストと共に各バリアントを返します。

{
  "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 を使用することもできます。

{
  "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 を使用し、特定のバリアントが配信時にどのように見えたかを確認します:

{
  "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 で利用可能です。完全なパターンはセールスエージェントのクリエイティブ機能を参照。

クロスエージェント集計

複数のセラーにわたってキャンペーンを実施する場合、各エージェントで get_creative_delivery を個別に呼び出して結果を相関させる:

結合キー: バイヤーが割り当てた creative_id を使用してエージェント間で同じクリエイティブを相関させる。アップロード時に concept_id を使用した場合、コンセプトでフィルタリングして関連するクリエイティブをグループ化します。
variant_id のスコープ: バリアント ID はエージェントとクリエイティブ内で一意であり、グローバルには一意ではありません。2つのエージェントが同じ variant_id 値を持つバリアントを生成する場合があります。集計ダッシュボードを構築する際はエージェント URL でプレフィックスを付ける。
タイムゾーン処理: 各エージェントは reporting_period.timezone を通じて独自のタイムゾーンでレポートする可能性があります。メトリクスを集計する前に共通のタイムゾーンに正規化します。
max_variants の選択: エージェントは max_variants が結果セットを制限する場合に返すバリアントを選択します。ほとんどのエージェントはインプレッション量（最も多く配信されたものが先）で優先度を付ける。代表的なサンプリングのためには、単一の大きな max_variants 値に頼るのではなく、異なる時間範囲で複数の呼び出しを行います。

クロスエージェントダッシュボードの構築

複数のエージェントからの配信データを統合ビューに集計する場合、以下の手順に従う:

収集: 同じ creative_ids フィルターを使用して、各エージェントで get_creative_delivery を並列に呼び出す。
タイムゾーンの正規化: 合計する前に各エージェントの reporting_period を共通のタイムゾーンに変換します。
creative_id でマージ: エージェント間で creative_id によって結果をグループ化します。totals（impressions、spend、clicks）を合計します。ctr などの派生メトリクスは平均しない — 合計されたコンポーネントから再計算します。
variant_id にプレフィックス: agent_url + variant_id を組み合わせてグローバルに一意なバリアントキーを作成する（例: https://sales.pinnaclemedia-example.com/var_a1b2c3）。これにより、2つのエージェントが独立して同じバリアント ID を割り当てた場合の衝突を防ぐ。
concept_id でグループ化: キャンペーンレベルのロールアップのために、concept_id を使用してサイズとセラーにわたる関連クリエイティブをグループ化します。コンセプトからクリエイティブへのマッピングは各エージェントの list_creatives から取得します。

// 疑似コード: 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" を宣言する:

{
  "creative_agents": [{
    "agent_url": "https://ads.seller-example.com",
    "capabilities": ["validation", "assembly", "preview", "delivery"]
  }]
}

バイヤーはこれを list_creative_formats を呼び出してケイパビリティに "delivery" を持つエージェントの creative_agents 配列を確認することで発見します。これはセールスエージェントを含む、クリエイティブプロトコルを実装するすべてのエージェントに適用されます。

はじめに

AdCP で構築する

プロトコル

FAQ

トラストとセキュリティ

リファレンス

AAO

認定

get_creative_delivery

リクエストパラメータ

レスポンス

クリエイティブオブジェクト

配信メトリクスフィールド

バリアントオブジェクト

Tier の動作

Tier 1: 標準クリエイティブ

プラットフォームエンゲージメントメトリクス

Tier 2: アセットグループ最適化

Tier 3: ジェネレーティブクリエイティブ

バリアントのプレビュー

配信レポートとの関係

クロスエージェント集計

クロスエージェントダッシュボードの構築

ケイパビリティ宣言

​リクエストパラメータ

​レスポンス

​クリエイティブオブジェクト

​配信メトリクスフィールド

​バリアントオブジェクト

​Tier の動作

​Tier 1: 標準クリエイティブ

​プラットフォームエンゲージメントメトリクス

​Tier 2: アセットグループ最適化

​Tier 3: ジェネレーティブクリエイティブ

​バリアントのプレビュー

​配信レポートとの関係

​クロスエージェント集計

​クロスエージェントダッシュボードの構築

​ケイパビリティ宣言

リクエストパラメータ

レスポンス

クリエイティブオブジェクト

配信メトリクスフィールド

バリアントオブジェクト

Tier の動作

Tier 1: 標準クリエイティブ

プラットフォームエンゲージメントメトリクス

Tier 2: アセットグループ最適化

Tier 3: ジェネレーティブクリエイティブ

バリアントのプレビュー

配信レポートとの関係

クロスエージェント集計

クロスエージェントダッシュボードの構築

ケイパビリティ宣言