Skip to main content
高度なフィルタリング、ソート、ページネーション、オプションのデータ拡張を備えたクリエイティブラ イブラリ検索タスクです。柔軟なクエリでクリエイティブアセットを効率よく探索・管理できます。 応答時間: 約 1 秒（シンプルな DB 参照）

​
概要

list_creatives はクリエイティブラ イブラリに対する包括的な検索・フィルタリング機能を提供します。複数のフィルター、ソート、ページネーション、割り当て/パフォーマンスなどの拡張データの含有をサポートします。 主な特徴:
  • 高度なフィルタリング: フォーマット、ステータス、タグ、日付、割り当てなどで検索
  • 柔軟なソート: 作成日、更新日、名前、ステータス、パフォーマンス指標で並べ替え
  • ページネーション: 大規模ライブラリを効率的に取得
  • データ拡張の任意指定: 割り当て情報、パフォーマンスデータ、サブアセットを必要に応じて含める
  • フィールド選択: 返却フィールドを限定しレスポンスサイズを最適化
  • タグベース探索: 「すべてのタグ一致」と「いずれかのタグ一致」に対応
  • 割り当てステータスでの絞り込み: 割り当て済み/未割り当て/特定パッケージ向けを検索

​
リクエストパラメーター

​
基本パラメーター

ParameterTypeRequiredDescription
filtersobjectNoクリエイティブ検索のフィルター条件
sortobjectNoソート条件
paginationobjectNoページネーション制御

​
データ含有オプション

ParameterTypeRequiredDescription
include_assignmentsbooleanNoパッケージ割り当て情報を含める（デフォルト: true）
include_performancebooleanNoパフォーマンス指標を含める（デフォルト: false）
include_sub_assetsbooleanNoカルーセル/ネイティブなどのサブアセットを含める（デフォルト: false）
fieldsarrayNo返却するフィールドを限定（未指定なら全フィールド）

​
フィルターオプション

​
フォーマットとステータス

{
  "filters": {
    "formats": ["video"],                           // フォーマット種別で絞り込み
    "statuses": ["approved", "pending_review"]      // ステータスで絞り込み
  }
}
アーカイブ済みクリエイティブはデフォルト除外です。 status: "archived" を指定するか、statuses 配列に "archived" を含めて明示的に取得してください。

​
タグフィルター

{
  "filters": {
    "tags": ["q1_2024", "video"],        // すべてのタグに一致 (AND)
    "tags_any": ["mobile", "desktop"]    // いずれかのタグに一致 (OR)
  }
}

​
テキスト検索

{
  "filters": {
    "name_contains": "nike",              // 名前の部分一致（大文字小文字を区別しない）
    "creative_ids": ["hero_video", "banner_300x250"] // 特定 ID
  }
}

​
日付範囲フィルター

{
  "filters": {
    "created_after": "2024-01-01T00:00:00Z",
    "created_before": "2024-12-31T23:59:59Z",
    "updated_after": "2024-06-01T00:00:00Z",
    "updated_before": "2024-06-30T23:59:59Z"
  }
}

​
割り当てステータス

{
  "filters": {
    "assigned_to_packages": ["pkg_ctv_001"],        // いずれかのパッケージに割り当て済み
    "media_buy_ids": ["mb_123", "mb_456"],          // いずれかのメディアバイに割り当て済み
    "buyer_refs": ["campaign_abc", "campaign_xyz"], // 該当 buyer_ref を持つメディアバイに割り当て済み
    "unassigned": true                              // 未割り当てのみ
  }
}

​
パフォーマンスフィルター

{
  "filters": {
    "has_performance_data": true          // パフォーマンスデータが存在するもののみ
  }
}

​
ソートオプション

昇順/降順を指定して並べ替えます。 
{
  "sort": {
    "field": "created_date",              // created_date, updated_date, name, status, assignment_count, performance_score
    "direction": "desc"                   // asc または desc
  }
}
利用可能なソートフィールド:
  • created_date - アップロード日時（デフォルト）
  • updated_date - 最終更新日時
  • name - クリエイティブ名（アルファベット順）
  • status - 審査ステータス
  • assignment_count - パッケージ割り当て数
  • performance_score - 集計パフォーマンス指標

​
ページネーション

結果件数とナビゲーションを制御します。 
{
  "pagination": {
    "limit": 50,                          // 1ページあたり最大件数 (1-100, デフォルト: 50)
    "offset": 0                           // スキップ件数 (デフォルト: 0)
  }
}

​
レスポンス形式

必要に応じた拡張データ付きでクリエイティブ情報を返却します。 
{
  "message": "Found 25 creatives matching your query",
  "context_id": "ctx_list_789012",
  "query_summary": {
    "total_matching": 25,
    "returned": 10,
    "filters_applied": ["format=video", "status=approved"]
  },
  "pagination": {
    "limit": 10,
    "offset": 0,
    "has_more": true,
    "total_pages": 3,
    "current_page": 1
  },
  "creatives": [
    {
      "creative_id": "hero_video_30s",
      "name": "Brand Hero Video 30s",
      "format_id": {
        "agent_url": "https://creative.adcontextprotocol.org",
        "id": "video_30s_vast"
      },
      "status": "approved",
      "created_date": "2024-01-15T10:30:00Z",
      "updated_date": "2024-01-15T14:20:00Z",
      // ... other creative fields
      "assignments": { /* include_assignments=true の場合 */ },
      "performance": { /* include_performance=true の場合 */ },
      "sub_assets": [ /* include_sub_assets=true の場合 */ ]
    }
  ],
  "format_summary": {
    "video_30s_vast": 15,
    "display_300x250": 8,
    "audio_30s": 2
  },
  "status_summary": {
    "approved": 20,
    "pending_review": 3,
    "rejected": 2,
    "archived": 5
  }
}

​
使用例

​
例 1: 基本的なライブラリ検索

承認済みの動画クリエイティブを一覧取得: 
{
  "filters": {
    "formats": ["video"],
    "statuses": ["approved"]
  },
  "sort": {
    "field": "created_date",
    "direction": "desc"
  },
  "pagination": {
    "limit": 20
  }
}

​
例 2: ブランドキャンペーン向け検索

Nike キャンペーンのクリエイティブをパフォーマンスデータ込みで取得: 
{
  "filters": {
    "name_contains": "nike",
    "has_performance_data": true,
    "created_after": "2024-01-01T00:00:00Z"
  },
  "include_performance": true,
  "sort": {
    "field": "performance_score",
    "direction": "desc"
  }
}

​
例 3: 未割り当てクリエイティブ

新規キャンペーンに割り当て可能なクリエイティブを取得: 
{
  "filters": {
    "unassigned": true,
    "statuses": ["approved"]
  },
  "sort": {
    "field": "created_date",
    "direction": "desc"
  },
  "pagination": {
    "limit": 50
  }
}

​
例 4: 特定パッケージ向け検索

特定パッケージに割り当てられたクリエイティブを取得: 
{
  "filters": {
    "assigned_to_packages": ["pkg_ctv_premium_001"]
  },
  "include_assignments": true,
  "include_performance": true,
  "sort": {
    "field": "assignment_count",
    "direction": "desc"
  }
}

​
例 5: 複数フォーマットのタグ検索

モバイル最適化されたクリエイティブを複数フォーマットで検索: 
{
  "filters": {
    "formats": ["display_320x50", "video_9x16_mobile", "display_300x250"],
    "tags_any": ["mobile_optimized", "responsive"],
    "statuses": ["approved"]
  },
  "sort": {
    "field": "updated_date",
    "direction": "desc"
  }
}

​
例 6: 特定フィールドのみ取得する軽量クエリ

UI ドロップダウン用に最小限の情報を取得: 
{
  "fields": ["creative_id", "name", "format", "status"],
  "include_assignments": false,
  "filters": {
    "statuses": ["approved"]
  },
  "sort": {
    "field": "name",
    "direction": "asc"
  }
}

​
例 7: ネイティブ広告テンプレートの探索

サブアセット付きのネイティブ広告テンプレートを検索: 
{
  "filters": {
    "formats": ["display_native_sponsored_post", "display_native_article"]
  },
  "include_sub_assets": true,
  "sort": {
    "field": "updated_date",
    "direction": "desc"
  }
}

​
例 8: 期間別の分析

特定の四半期にアップロードされたクリエイティブを分析: 
{
  "filters": {
    "created_after": "2024-01-01T00:00:00Z",
    "created_before": "2024-03-31T23:59:59Z"
  },
  "include_performance": true,
  "sort": {
    "field": "created_date",
    "direction": "asc"
  },
  "pagination": {
    "limit": 100
  }
}

​
例 9: キャンペーン単位の検索

特定メディアバイ/キャンペーンで使用されたクリエイティブを取得: 
{
  "filters": {
    "media_buy_ids": ["mb_summer_2025", "mb_spring_2025"],
    "statuses": ["approved"]
  },
  "include_assignments": true,
  "include_performance": true,
  "sort": {
    "field": "performance_score",
    "direction": "desc"
  }
}

​
例 10: buyer_ref で検索

関連キャンペーンにまたがって buyer_ref でクリエイティブを検索: 
{
  "filters": {
    "buyer_refs": ["nike_q2_2024", "nike_summer_sale"],
    "formats": ["video", "display"]
  },
  "include_assignments": true,
  "sort": {
    "field": "updated_date",
    "direction": "desc"
  }
}

​
例 11: アーカイブ済みを取得

デフォルトでは除外されるアーカイブ済みクリエイティブを表示: 
{
  "filters": {
    "status": "archived"
  },
  "sort": {
    "field": "updated_date",
    "direction": "desc"
  }
}

​
クエリ最適化のヒント

​
1. 具体的なフィルターを使う

  • まずフォーマットで絞り込み、結果を狭める
  • ステータスでアクション可能なものに集中
  • 複数フィルターを組み合わせ、精度を高める

​
2. フィールド選択の最適化

  • fields で必要なデータだけを返却
  • 割り当て情報が不要な場合は include_assignments: false
  • パフォーマンス分析が必要なときだけパフォーマンスデータを要求

​
3. ページネーション戦略

  • インタラクティブ UI では少量（10-20 件）から開始
  • バルク処理では大きめ（50-100 件）を使用
  • has_more を見て効率的にページング

​
4. ソートの考慮

  • 時系列で見るなら created_date
  • 効果重視なら performance_score
  • アルファベット順なら name

​
フィルター組み合わせ例

最近の高パフォーマンスクリエイティブ: 
{
  "filters": {
    "has_performance_data": true,
    "created_after": "2024-01-01T00:00:00Z"
  },
  "sort": { "field": "performance_score", "direction": "desc" },
  "include_performance": true
}
割り当て準備完了のクリエイティブ: 
{
  "filters": {
    "statuses": ["approved"],
    "unassigned": true
  },
  "sort": { "field": "created_date", "direction": "desc" }
}
キャンペーン固有検索: 
{
  "filters": {
    "tags": ["q2_2024", "brand_awareness"],
    "formats": ["video", "display"]
  },
  "sort": { "field": "updated_date", "direction": "desc" }
}

​
エラーハンドリング

​
無効なフィルター値

フィルターに不正値がある場合、具体的なエラーを返します。 
{
  "message": "Query validation failed",
  "errors": [
    "Invalid format: 'invalid_format' does not match any known format",
    "Invalid sort field: 'invalid_field' must be one of [created_date, updated_date, name, status, assignment_count, performance_score]"
  ]
}

​
大規模な結果セット

非常に大きな結果が返る場合: 
{
  "message": "Query returned 10,000+ results, consider adding more specific filters",
  "query_summary": {
    "total_matching": 10247,
    "returned": 50
  }
}

​
パフォーマンス上の注意

​
1. 早期フィルター

  • 最も選択度の高いフィルターを優先
  • フォーマット/ステータスで結果を削減
  • 日付範囲と組み合わせて効率化

​
2. 適切なページネーション

  • 100 件超の大きすぎるページはタイムアウトしやすい
  • 一貫性が必要なら offset ベースを利用
  • 非常に大きい場合はカーソルベースも検討

​
3. フィールド選択

  • fields で必要なフィールドのみ取得
  • パフォーマンス指標は分析時だけ要求
  • ドロップダウン/オートコンプリートでは最小限のフィールドを使用

​
連携パターン

​
クリエイティブ選択 UI

// ドロップダウン用の軽量リストを取得
const response = await adcp.list_creatives({
  fields: ["creative_id", "name", "format"],
  filters: { statuses: ["approved"] },
  sort: { field: "name", direction: "asc" },
  include_assignments: false
});

​
パフォーマンスダッシュボード

// パフォーマンス指標付きで上位クリエイティブを取得
const response = await adcp.list_creatives({
  filters: { 
    has_performance_data: true,
    created_after: "2024-01-01T00:00:00Z"
  },
  sort: { field: "performance_score", direction: "desc" },
  include_performance: true,
  pagination: { limit: 10 }
});

​
割り当て管理

// 未割り当てで新規キャンペーンに使えるクリエイティブを検索
const response = await adcp.list_creatives({
  filters: {
    unassigned: true,
    statuses: ["approved"],
    formats: ["video", "display"]
  },
  sort: { field: "created_date", direction: "desc" }
});
  • sync_creatives - クリエイティブアセットのアップロードと管理
  • create_media_buy - ライブラリのクリエイティブでキャンペーンを作成
  • list_creative_formats - サポートされるクリエイティブフォーマットの探索
list_creatives タスクは強力なクエリ機能を提供し、複雑なワークフローでもクリエイティブアセットを効率的に探索・分析・管理できます。