AdCP — list_creatives

クリエイティブライブラリ内のクリエイティブをブラウズ・フィルタリングします。フォーマット、ステータス、コンセプト、タグ、日付範囲、ダイナミック変数によるフィルタリング、ページネーション、オプションのフィールドエンリッチメントをサポートします。クリエイティブライブラリをホストするすべてのエージェント — クリエイティブエージェント（広告サーバー、クリエイティブ管理プラットフォーム）およびクリエイティブを管理するセールスエージェント — が実装します。 レスポンスタイム: ~1秒（シンプルなデータベースルックアップ）

概要

主な機能:

フォーマット、ステータス、タグ、日付、アサインメント、コンセプト、変数でフィルタリング
作成日、更新日、名前、ステータス、アサインメント数でソート
大きなライブラリのためのカーソルベースのページネーション
アサインメント、配信スナップショット、アイテム、ダイナミッククリエイティブ最適化（DCO）変数をオプションで含めます
レスポンスサイズを削減するために特定のフィールドのみを返す
クリエイティブコンセプトでフィルタリング（サイズ/フォーマットをまたぐ関連クリエイティブのグループ）
DCO クリエイティブを見つけてダイナミックコンテンツスロットを確認します

リクエストパラメータ

スキーマ: creative/list-creatives-request.json

コアパラメータ

パラメータ	タイプ	必須	説明
`filters`	object	No	フィルター条件 — 以下のフィルタリングオプションを参照
`sort`	object	No	ソートパラメータ
`pagination`	object	No	ページネーション制御

データ含有オプション

パラメータ	タイプ	必須	説明
`include_assignments`	boolean	No	パッケージアサインメント情報を含める（デフォルト: true）
`include_snapshot`	boolean	No	軽量な配信スナップショットを含める — ライフタイムインプレッションと最終配信日時（デフォルト: false）。詳細なアナリティクスには `get_creative_delivery` を使用します。
`include_items`	boolean	No	カルーセルやネイティブ広告などのマルチアセットフォーマットのアイテムを含める（デフォルト: false）
`include_variables`	boolean	No	ダイナミックコンテンツ変数定義を含める（デフォルト: false）
`include_pricing`	boolean	No	各クリエイティブに `pricing_options` を含める（デフォルト: false）。`account` が必要。
`include_purged`	boolean	No	ソフトパージされたクリエイティブのトゥームストーンを含める（デフォルト: false）。パージされたトゥームストーンを参照。
`include_webhook_activity`	boolean	No	クリエイティブごとの最近のウェブフック発火を含める（デフォルト: false）。ウェブフックアクティビティを参照。
`webhook_activity_limit`	integer	No	`include_webhook_activity: true` のときのクリエイティブごとの `webhook_activity[]` レコードの最大数（デフォルト: 50、範囲 1〜200）。
`account`	AccountRef	No	価格のためのアカウント参照。`include_pricing` とともに提供された場合、エージェントは各クリエイティブにこのアカウントのレートカードから `pricing_options` を返します。
`fields`	array	No	返す特定のフィールド（すべてのフィールドを返すには省略）。スパースな選択のために `"pricing_options"` を含みます。

フィルタリングオプション

filters オブジェクトは以下のオプションの組み合わせ可能なフィルターをサポートする:

フィルター	タイプ	説明
`accounts`	AccountRef[]	所有アカウントでフィルタリング
`format_ids`	FormatID[]	構造化フォーマット ID でフィルタリング
`statuses`	CreativeStatus[]	承認ステータスでフィルタリング
`tags`	string[]	タグでフィルタリング（すべてが一致する必要があります）
`tags_any`	string[]	タグでフィルタリング（いずれかが一致すればよい）
`name_contains`	string	大文字小文字を区別しない名前検索
`creative_ids`	string[]	特定のクリエイティブ ID でフィルタリング（最大100）
`concept_ids`	string[]	コンセプトグループでフィルタリング
`has_variables`	boolean	ダイナミック変数を持つ DCO クリエイティブでフィルタリング
`created_after` / `created_before`	date-time	作成日範囲でフィルタリング
`updated_after` / `updated_before`	date-time	最終更新日範囲でフィルタリング
`assigned_to_packages`	string[]	パッケージアサインメントでフィルタリング *
`media_buy_ids`	string[]	メディアバイアサインメントでフィルタリング *
`unassigned`	boolean	未アサインのクリエイティブでフィルタリング *
`has_served`	boolean	少なくとも1つのインプレッションが配信されたクリエイティブでフィルタリング *

* アサインメント関連フィルターはセールスエージェント固有。スタンドアロンクリエイティブエージェントはこれらを無視します。

アーカイブ済みクリエイティブはデフォルトで除外されます。 結果にアーカイブ済みクリエイティブを含めるには、statuses 配列に明示的に "archived" を含めます。サスペンドされたクリエイティブはアーカイブされていません。認可が期限切れの公開済み投稿の参照のような、回復可能なオフラインのクリエイティブを特に含めたい場合は "suspended" を含めます。

公開済み投稿の参照プロダクトでは、list_creatives はセラーが検査を認可されている下流のパブリッシャーのアイデンティティに限定されます。プロダクトが publisher_identity のような 2 つ目のプラットフォーム接続を必要とし、それが欠けている場合、セラーは error.details.missing_connections[] を伴う AUTHORIZATION_REQUIRED を返すべきです。list_creatives をグローバルなプラットフォーム投稿検索として提示すべきではありません。

ソートオプション

昇順または降順でさまざまなフィールドでソートする:

{
  "sort": {
    "field": "created_date",
    "direction": "desc"
  }
}

利用可能なソートフィールド:

created_date - クリエイティブが作成された日時（デフォルト）
updated_date - クリエイティブが最後に変更された日時
name - クリエイティブ名（アルファベット順）
status - 承認ステータス
assignment_count - パッケージアサインメント数

ページネーション

カーソルベースのページネーションで結果セットのサイズを制御する:

{
  "pagination": {
    "max_results": 50,
    "cursor": "eyJjcmVhdGVkX2RhdGUiOi4uLn0"
  }
}

レスポンスフォーマット

スキーマ: creative/list-creatives-response.json レスポンスはオプションのエンリッチメントを持つクリエイティブデータを提供します:

{
  "query_summary": {
    "total_matching": 1,
    "returned": 1,
    "filters_applied": ["status=approved"]
  },
  "pagination": {
    "has_more": false,
    "total_count": 1
  },
  "creatives": [
    {
      "creative_id": "ft_88201",
      "name": "Holiday Sale - Medium Rectangle",
      "format_id": {
        "agent_url": "https://creative.example.com",
        "id": "display_static",
        "width": 300,
        "height": 250
      },
      "status": "approved",
      "created_date": "2026-01-15T10:30:00Z",
      "updated_date": "2026-01-15T14:20:00Z",
      "concept_id": "concept_holiday_2026",
      "concept_name": "Holiday 2026 Campaign",
      "variables": [
        {
          "variable_id": "headline_text",
          "name": "Headline",
          "variable_type": "text",
          "default_value": "Holiday Sale - 50% Off",
          "required": true
        }
      ]
    }
  ],
  "format_summary": {
    "display_static_300x250": 1
  },
  "status_summary": {
    "approved": 1
  }
}

クリエイティブごとのフィールド

フィールド	タイプ	説明
`creative_id`	string	一意のクリエイティブ識別子
`name`	string	人間が読める名前
`format_id`	object	構造化フォーマット参照
`status`	string	承認ステータス
`created_date`	string	作成タイムスタンプ
`updated_date`	string	最終変更タイムスタンプ
`assets`	object	クリエイティブアセット（画像、テキスト、URL など）
`tags`	string[]	分類用タグ
`concept_id`	string	クリエイティブコンセプト ID
`concept_name`	string	人間が読めるコンセプト名
`variables`	array	DCO 変数定義（`include_variables=true` の場合）
`assignments`	object	パッケージアサインメント（`include_assignments=true` の場合）
`snapshot`	object	配信スナップショット（`include_snapshot=true` の場合）
`snapshot_unavailable_reason`	string	スナップショットが欠けている理由 — `SNAPSHOT_UNSUPPORTED`、`SNAPSHOT_TEMPORARILY_UNAVAILABLE`、または `SNAPSHOT_PERMISSION_DENIED`
`items`	array	マルチアセットフォーマットのアイテム（`include_items=true` の場合）
`pricing_options`	VendorPricingOption[]	このクリエイティブの価格オプション（`include_pricing=true` かつ `account` 提供時）。ベンダーは複数のオプションを提供できます（ボリュームティア、コンテキスト固有のレート、プロダクトラインごとの異なるモデル）。`get_signals` や `list_content_standards` と同じパターン。

価格

include_pricing=true かつ account が提供された場合、各クリエイティブにはアカウントのレートカードから pricing_options が含まれます:

{
  "pricing_options": [
    {
      "pricing_option_id": "po_video_cpm",
      "model": "cpm",
      "cpm": 0.50,
      "currency": "USD"
    }
  ]
}

バイヤーは、請求の検証のために、適用された pricing_option_id（build_creative レスポンスから）を report_usage で渡します。ベンダーは複数のオプションを提供できます——ボリューム/コミットメントのティア、コンテキスト固有のレート（プレミアム vs 標準のプレースメント）、または異なるプロダクトラインの完全に異なる価格モデル。これはシグナルとコンテンツ標準が使うのと同じパターンです。

配信スナップショット

include_snapshot=true の場合、各クリエイティブには「このクリエイティブはアクティブか?」「最後にいつ配信されたか?」などの運用上の質問のための軽量な配信スナップショットが含まれます。これはアナリティクスではない — 詳細なパフォーマンスデータには get_creative_delivery を使用します。

{
  "snapshot": {
    "as_of": "2026-03-08T14:30:00Z",
    "staleness_seconds": 3600,
    "impressions": 145200,
    "last_served": "2026-03-07T22:15:00Z"
  }
}

フィールド	タイプ	必須	説明
`as_of`	date-time	Yes	このスナップショットがキャプチャされた日時
`staleness_seconds`	integer	Yes	データの最大経過時間（秒）
`impressions`	integer	Yes	ライフタイムインプレッション（任意の日付範囲にスコープされていない）
`last_served`	date-time	No	このクリエイティブが最後に配信された日時。一度も配信されていない場合は存在しません。

パージされたトゥームストーン

クリエイティブが creative.purged を介して purge_kind: soft で破棄されると、セラーはパージのタイムスタンプから 30 日間トゥームストーンを保持します。トゥームストーンは、リクエストが include_purged: true を設定した場合にのみ list_creatives に現れます:

{
  "creative_id": "ft_87100",
  "name": "Holiday Sale - Leaderboard (purged)",
  "status": "approved",
  "purge": {
    "kind": "soft",
    "at": "2026-05-18T02:59:48Z",
    "reason_code": "retention_expired"
  }
}

トゥームストーンの status フィールドは、パージ前の値で凍結されます（上記の例では、"approved" はパージ直前のクリエイティブの状態であって、現在の主張ではありません）。バイヤーはクリエイティブを消滅したものとして扱わなければなりません（MUST）: 割り当て、配信操作、デリバリーの読み取りはもう適用されません。purge ブロックの存在が明確なシグナルです。ハードパージされたクリエイティブ（purge_kind: hard、GDPR 第 17 条 / CCPA / 同等法の下での法的消去に使用）はトゥームストーンを保持しません。creative.purged ウェブフックが唯一のシグナルです。根拠については snapshot-and-log § ルール 4 の除外を参照してください。

ウェブフックアクティビティ

include_webhook_activity: true の場合、返される各クリエイティブは、そのクリエイティブにスコープされた最近の発火——creative.status_changed と creative.purged の配信——の webhook_activity[] 配列を運びます。これは「パブリッシャーは発火したか? 自分のエンドポイントは受信したか? リトライの軌跡はクリーンか?」というバイヤーのデバッグ用サーフェスです——get_media_buys の webhook_activity[] と同じ形状と契約です。完全な規範的契約（保持、三状態の存在、リクエストフィールドの慣例）についてはウェブフックアクティビティログのパターンを参照してください。これらの発火にサブスクライブするには、sync_accounts を介してアカウントに notification_configs[] エントリを登録します。セラーは、event_types[] にそのタイプを含む各エントリに対してサブスクライバーごとに発火します。この読み取りの webhook_activity[] は、実際に何が発火したかのバイヤー側のデバッグログです。三状態の存在が適用されます:

フィールドが省略 — セラーはこの読み取りでウェブフックアクティビティを公開しない。
[] — セラーはフィールドを公開するが、このクリエイティブについて保持ウィンドウ内に発火がない。
空でない — 実際のレコード、新しい順、webhook_activity_limit（最大 200）で上限。

エンドポイントのログには idempotency_key で相関させます。各レコードの notification_type が発火の種類を判別します:

{
  "webhook_activity": [
    {
      "idempotency_key": "whk_01HW9D2T3VXQ5M7K9N1P3R5S7U",
      "subscriber_id": "buyer-primary",
      "fired_at": "2026-05-18T14:20:00Z",
      "completed_at": "2026-05-18T14:20:00Z",
      "notification_type": "creative.status_changed",
      "attempt": 1,
      "status": "success",
      "url": "https://buyer.example/webhooks/adcp/creative",
      "http_status_code": 200,
      "response_time_ms": 142,
      "payload_size_bytes": 612,
      "error_message": null
    }
  ]
}

バイヤーは「発火が届かなかった」を、次を組み合わせて診断します: (a) list_accounts.accounts[].notification_configs[] 上のサブスクライバー登録状態——正しい URL が正しい event_types[] でアクティブか?——と (b) get_adcp_capabilities を介したセラーのケイパビリティ宣言——セラーは自分がサブスクライブしたイベントタイプをサポートするか?。webhook_activity のフィールド省略だけでは、「セラーがログを公開しない」と「発火が起きなかった」を区別できません。

バイヤーのハンドラー（エンドツーエンド）

バイヤーの creative.status_changed 用ウェブフックハンドラーは、各発火を creative_id を介してライブラリの状態と相関させ、idempotency_key で重複排除し、権威あるスナップショットのために list_creatives を再読み込みします（snapshot-and-log ルール 3 に従う）:

// POST /webhooks/adcp/creative
async function handleCreativeWebhook(req, res) {
  // 1. Verify signature per the registered scheme (RFC 9421 by default).
  if (!verifyWebhookSignature(req)) return res.status(401).end();

  const fire = req.body; // creative-status-changed-webhook or creative-purged-webhook
  const { notification_type, idempotency_key, creative_id, account_id } = fire;

  // 2. Dedupe at-least-once delivery.
  if (await alreadyProcessed(idempotency_key)) return res.status(200).end();

  // 3. Re-read snapshot for authoritative state. Push is signal; snapshot is truth.
  const snapshot = await testAgent.listCreatives({
    filters: { creative_ids: [creative_id] },
    include_purged: notification_type === "creative.purged"
  });

  // 4. Apply local effects from the snapshot, not the webhook payload.
  await reconcileCreative(snapshot.creatives[0]);

  await markProcessed(idempotency_key);
  return res.status(200).end();
}

このハンドラーが避ける二つの落とし穴: (1) ウェブフックのペイロードから直接状態を適用すること（順序と再発行がペイロードを非権威的にします）、(2) 重複排除をスキップすること（セラーは 2xx 以外でリトライし、見逃しイベントの警告で再発行します）。

アカウント要件

ライブラリをホストするクリエイティブエージェントはバイヤーがクリエイティブをクエリする前にアクセスを確立できるよう accounts プロトコル（sync_accounts / list_accounts）を実装すべきです。これはセールスエージェントがメディアバイのために使用するのと同じ accounts プロトコルだ — 別バージョンはない。メディアバイのために accounts プロトコルを既に実装しているセールスエージェントは追加対応不要です。

使用例

変数を含むコンセプトスコープのクエリ

特定のコンセプト内のすべての承認済みクリエイティブを DCO 変数定義と共にリスト:

{
  "filters": {
    "concept_ids": ["concept_holiday_2026"],
    "statuses": ["approved"]
  },
  "include_variables": true,
  "sort": {
    "field": "created_date",
    "direction": "desc"
  }
}

フォーマット固有のクエリ

コンセプトをまたいで特定のフォーマット ID に一致するクリエイティブを検索:

{
  "filters": {
    "format_ids": [
      {
        "agent_url": "https://creative.example.com",
        "id": "display_static",
        "width": 300,
        "height": 250
      },
      {
        "agent_url": "https://creative.example.com",
        "id": "display_static",
        "width": 728,
        "height": 90
      }
    ],
    "statuses": ["approved"]
  }
}

DCO クリエイティブの検索

パーソナライズキャンペーン用のダイナミックコンテンツ変数を持つクリエイティブを検索:

{
  "filters": {
    "has_variables": true,
    "statuses": ["approved"]
  },
  "include_variables": true
}

フィールド制限クエリ

選択ドロップダウン用の最小限のクリエイティブデータを取得:

{
  "fields": ["creative_id", "name", "format_id", "status"],
  "include_assignments": false,
  "filters": {
    "statuses": ["approved"]
  },
  "sort": {
    "field": "name",
    "direction": "asc"
  }
}

ライブラリヘルスチェック

休眠しているアセットを特定するために配信スナップショットと共にアクティブなクリエイティブを検索:

{
  "filters": {
    "media_buy_ids": ["mb_summer_2026", "mb_spring_2026"],
    "statuses": ["approved"]
  },
  "include_assignments": true,
  "include_snapshot": true,
  "sort": {
    "field": "updated_date",
    "direction": "desc"
  }
}

はじめに

AdCP で構築する

プロトコル

FAQ

トラストとセキュリティ

リファレンス

AAO

認定

list_creatives

概要

リクエストパラメータ

コアパラメータ

データ含有オプション

フィルタリングオプション

ソートオプション

ページネーション

レスポンスフォーマット

クリエイティブごとのフィールド

価格

配信スナップショット

パージされたトゥームストーン

ウェブフックアクティビティ

バイヤーのハンドラー（エンドツーエンド）

アカウント要件

使用例

変数を含むコンセプトスコープのクエリ

フォーマット固有のクエリ

DCO クリエイティブの検索

フィールド制限クエリ

ライブラリヘルスチェック

関連タスク

​概要

​リクエストパラメータ

​コアパラメータ

​データ含有オプション

​フィルタリングオプション

​ソートオプション

​ページネーション

​レスポンスフォーマット

​クリエイティブごとのフィールド

​価格

​配信スナップショット

​パージされたトゥームストーン

​ウェブフックアクティビティ

​バイヤーのハンドラー（エンドツーエンド）

​アカウント要件

​使用例

​変数を含むコンセプトスコープのクエリ

​フォーマット固有のクエリ

​DCO クリエイティブの検索

​フィールド制限クエリ

​ライブラリヘルスチェック

​関連タスク

概要

リクエストパラメータ

コアパラメータ

データ含有オプション

フィルタリングオプション

ソートオプション

ページネーション

レスポンスフォーマット

クリエイティブごとのフィールド

価格

配信スナップショット

パージされたトゥームストーン

ウェブフックアクティビティ

バイヤーのハンドラー（エンドツーエンド）

アカウント要件

使用例

変数を含むコンセプトスコープのクエリ

フォーマット固有のクエリ

DCO クリエイティブの検索

フィールド制限クエリ

ライブラリヘルスチェック

関連タスク