> ## 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. # list_creatives > list_creatives はカーソルベースのページネーションを使用して AdCP ライブラリ内のクリエイティブをフォーマット、ステータス、コンセプト、タグでブラウズ・フィルタリングします。 クリエイティブライブラリ内のクリエイティブをブラウズ・フィルタリングします。フォーマット、ステータス、コンセプト、タグ、日付範囲、ダイナミック変数によるフィルタリング、ページネーション、オプションのフィールドエンリッチメントをサポートします。 クリエイティブライブラリをホストするすべてのエージェント — クリエイティブエージェント（広告サーバー、クリエイティブ管理プラットフォーム）およびクリエイティブを管理するセールスエージェント — が実装します。 **レスポンスタイム**: \~1秒（シンプルなデータベースルックアップ） ## 概要 **主な機能:** * フォーマット、ステータス、タグ、日付、アサインメント、コンセプト、変数でフィルタリング * 作成日、更新日、名前、ステータス、アサインメント数でソート * 大きなライブラリのためのカーソルベースのページネーション * アサインメント、配信スナップショット、アイテム、ダイナミッククリエイティブ最適化（DCO）変数をオプションで含めます * レスポンスサイズを削減するために特定のフィールドのみを返す * クリエイティブコンセプトでフィルタリング（サイズ/フォーマットをまたぐ関連クリエイティブのグループ） * DCO クリエイティブを見つけてダイナミックコンテンツスロットを確認します ## リクエストパラメータ **スキーマ**: [`creative/list-creatives-request.json`](https://adcontextprotocol.org/schemas/v3/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`](/docs/creative/task-reference/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](/docs/building/by-layer/L2/accounts-and-agents#account-references) | No | 価格のためのアカウント参照。`include_pricing` とともに提供された場合、エージェントは各クリエイティブにこのアカウントのレートカードから `pricing_options` を返します。 | | `fields` | array | No | 返す特定のフィールド（すべてのフィールドを返すには省略）。スパースな選択のために `"pricing_options"` を含みます。 | ## フィルタリングオプション `filters` オブジェクトは以下のオプションの組み合わせ可能なフィルターをサポートする: | フィルター | タイプ | 説明 | | ---------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------- | | `accounts` | [AccountRef](/docs/building/by-layer/L2/accounts-and-agents#account-references)\[] | 所有アカウントでフィルタリング | | `format_ids` | FormatID\[] | 構造化フォーマット ID でフィルタリング | | `statuses` | [CreativeStatus](/docs/creative/specification#クリエイティブステータスのライフサイクル)\[] | 承認ステータスでフィルタリング | | `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` をグローバルなプラットフォーム投稿検索として提示すべきではありません。 ## ソートオプション 昇順または降順でさまざまなフィールドでソートする: ```json theme={null} { "sort": { "field": "created_date", "direction": "desc" } } ``` **利用可能なソートフィールド:** * `created_date` - クリエイティブが作成された日時（デフォルト） * `updated_date` - クリエイティブが最後に変更された日時 * `name` - クリエイティブ名（アルファベット順） * `status` - 承認ステータス * `assignment_count` - パッケージアサインメント数 ## ページネーション カーソルベースのページネーションで結果セットのサイズを制御する: ```json theme={null} { "pagination": { "max_results": 50, "cursor": "eyJjcmVhdGVkX2RhdGUiOi4uLn0" } } ``` ## レスポンスフォーマット **スキーマ**: [`creative/list-creatives-response.json`](https://adcontextprotocol.org/schemas/v3/creative/list-creatives-response.json) レスポンスはオプションのエンリッチメントを持つクリエイティブデータを提供します: ```json theme={null} { "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](/docs/creative/specification#価格)\[] | このクリエイティブの価格オプション（`include_pricing=true` かつ `account` 提供時）。ベンダーは複数のオプションを提供できます（ボリュームティア、コンテキスト固有のレート、プロダクトラインごとの異なるモデル）。`get_signals` や `list_content_standards` と同じパターン。 | ### 価格 `include_pricing=true` かつ `account` が提供された場合、各クリエイティブにはアカウントのレートカードから `pricing_options` が含まれます: ```json theme={null} { "pricing_options": [ { "pricing_option_id": "po_video_cpm", "model": "cpm", "cpm": 0.50, "currency": "USD" } ] } ``` バイヤーは、請求の検証のために、適用された `pricing_option_id`（`build_creative` レスポンスから）を `report_usage` で渡します。ベンダーは複数のオプションを提供できます——ボリューム/コミットメントのティア、コンテキスト固有のレート（プレミアム vs 標準のプレースメント）、または異なるプロダクトラインの完全に異なる価格モデル。これは[シグナル](/docs/signals/tasks/get_signals)と[コンテンツ標準](/docs/governance/content-standards/index)が使うのと同じパターンです。 ### 配信スナップショット `include_snapshot=true` の場合、各クリエイティブには「このクリエイティブはアクティブか?」「最後にいつ配信されたか?」などの運用上の質問のための軽量な配信スナップショットが含まれます。これはアナリティクスではない — 詳細なパフォーマンスデータには [`get_creative_delivery`](/docs/creative/task-reference/get_creative_delivery) を使用します。 ```json theme={null} { "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`](https://adcontextprotocol.org/schemas/v3/creative/creative-purged-webhook.json) を介して `purge_kind: soft` で破棄されると、セラーはパージのタイムスタンプから 30 日間トゥームストーンを保持します。トゥームストーンは、リクエストが `include_purged: true` を設定した場合にのみ `list_creatives` に現れます: ```json theme={null} { "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`](https://adcontextprotocol.org/schemas/v3/creative/creative-purged-webhook.json) ウェブフックが唯一のシグナルです。根拠については [snapshot-and-log § ルール 4 の除外](/docs/protocol/snapshot-and-log#account-level-adopters-3-1)を参照してください。 ### ウェブフックアクティビティ `include_webhook_activity: true` の場合、返される各クリエイティブは、そのクリエイティブにスコープされた最近の発火——`creative.status_changed` と `creative.purged` の配信——の `webhook_activity[]` 配列を運びます。これは「パブリッシャーは発火したか? 自分のエンドポイントは受信したか? リトライの軌跡はクリーンか?」というバイヤーのデバッグ用サーフェスです——`get_media_buys` の `webhook_activity[]` と同じ形状と契約です。完全な規範的契約（保持、三状態の存在、リクエストフィールドの慣例）については[ウェブフックアクティビティログのパターン](/docs/protocol/snapshot-and-log#webhook-activity-log-pattern)を参照してください。 これらの発火に**サブスクライブする**には、`sync_accounts` を介してアカウントに [`notification_configs[]`](/docs/accounts/tasks/sync_accounts#account-level-webhook-subscriptions) エントリを登録します。セラーは、`event_types[]` にそのタイプを含む各エントリに対してサブスクライバーごとに発火します。この読み取りの `webhook_activity[]` は、実際に何が発火したかのバイヤー側のデバッグログです。 三状態の存在が適用されます: * **フィールドが省略** — セラーはこの読み取りでウェブフックアクティビティを公開しない。 * **`[]`** — セラーはフィールドを公開するが、このクリエイティブについて保持ウィンドウ内に発火がない。 * **空でない** — 実際のレコード、新しい順、`webhook_activity_limit`（最大 200）で上限。 エンドポイントのログには `idempotency_key` で相関させます。各レコードの `notification_type` が発火の種類を判別します: ```json theme={null} { "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](/docs/protocol/snapshot-and-log#the-five-rules) に従う）: ```javascript theme={null} // 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 プロトコル](/docs/accounts/overview)（`sync_accounts` / `list_accounts`）を実装すべきです。これはセールスエージェントがメディアバイのために使用するのと同じ accounts プロトコルだ — 別バージョンはない。メディアバイのために accounts プロトコルを既に実装しているセールスエージェントは追加対応不要です。 ## 使用例 ### 変数を含むコンセプトスコープのクエリ 特定のコンセプト内のすべての承認済みクリエイティブを DCO 変数定義と共にリスト: ```json theme={null} { "filters": { "concept_ids": ["concept_holiday_2026"], "statuses": ["approved"] }, "include_variables": true, "sort": { "field": "created_date", "direction": "desc" } } ``` ### フォーマット固有のクエリ コンセプトをまたいで特定のフォーマット ID に一致するクリエイティブを検索: ```json theme={null} { "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 クリエイティブの検索 パーソナライズキャンペーン用のダイナミックコンテンツ変数を持つクリエイティブを検索: ```json theme={null} { "filters": { "has_variables": true, "statuses": ["approved"] }, "include_variables": true } ``` ### フィールド制限クエリ 選択ドロップダウン用の最小限のクリエイティブデータを取得: ```json theme={null} { "fields": ["creative_id", "name", "format_id", "status"], "include_assignments": false, "filters": { "statuses": ["approved"] }, "sort": { "field": "name", "direction": "asc" } } ``` ### ライブラリヘルスチェック 休眠しているアセットを特定するために配信スナップショットと共にアクティブなクリエイティブを検索: ```json theme={null} { "filters": { "media_buy_ids": ["mb_summer_2026", "mb_spring_2026"], "statuses": ["approved"] }, "include_assignments": true, "include_snapshot": true, "sort": { "field": "updated_date", "direction": "desc" } } ``` ## 関連タスク * [`get_creative_delivery`](/docs/creative/task-reference/get_creative_delivery) - 日付範囲、バリアント内訳、完全な配信メトリクスを含む詳細なパフォーマンスアナリティクス * [`build_creative`](/docs/creative/task-reference/build_creative) - ライブラリクリエイティブからマニフェストをビルドするか、ゼロから生成します * [`sync_creatives`](/docs/creative/task-reference/sync_creatives) - クリエイティブライブラリをホストするすべてのエージェントでクリエイティブアセットをアップロードして管理します * [`list_creative_formats`](/docs/creative/task-reference/list_creative_formats) - サポートされているクリエイティブフォーマットを発見します * [`preview_creative`](/docs/creative/task-reference/preview_creative) - クリエイティブマニフェストのプレビューを生成します