AdCP — list_creatives

Browse and filter creatives in a creative library. Supports filtering by format, status, concept, tags, date range, and dynamic variables, with pagination and optional field enrichment. Implemented by any agent that hosts a creative library — creative agents (ad servers, creative management platforms) and sales agents that manage creatives. Response time: ~1 second (simple database lookup)

Overview

Key features:

Filter by format, status, tags, dates, assignments, concepts, and variables
Sort by creation date, update date, name, status, or assignment count
Cursor-based pagination for large libraries
Optionally include assignments, delivery snapshots, items, and dynamic creative optimization (DCO) variables
Return only specific fields to reduce response size
Filter by creative concept (groups of related creatives across sizes/formats)
Find DCO creatives and inspect their dynamic content slots

Request parameters

Schema: creative/list-creatives-request.json

Core parameters

Parameter	Type	Required	Description
`filters`	object	No	Filter criteria — see filtering options below
`sort`	object	No	Sorting parameters
`pagination`	object	No	Pagination controls

Data inclusion options

Parameter	Type	Required	Description
`include_assignments`	boolean	No	Include package assignment information (default: true)
`include_snapshot`	boolean	No	Include a lightweight delivery snapshot — lifetime impressions and last-served date (default: false). For detailed analytics, use `get_creative_delivery`.
`include_items`	boolean	No	Include items for multi-asset formats like carousels and native ads (default: false)
`include_variables`	boolean	No	Include dynamic content variable definitions (default: false)
`fields`	array	No	Specific fields to return (omit for all fields)

Filtering options

The filters object supports these optional, composable filters:

Filter	Type	Description
`accounts`	array	Filter by owning accounts
`format_ids`	format_id[]	Filter by structured format IDs
`statuses`	string[]	Filter by approval status
`tags`	string[]	Filter by tags (all must match)
`tags_any`	string[]	Filter by tags (any must match)
`name_contains`	string	Case-insensitive name search
`creative_ids`	string[]	Filter by specific creative IDs (max 100)
`concept_ids`	string[]	Filter by concept groupings
`has_variables`	boolean	Filter for DCO creatives with dynamic variables
`created_after` / `created_before`	date-time	Filter by creation date range
`updated_after` / `updated_before`	date-time	Filter by last-modified date range
`assigned_to_packages`	string[]	Filter by package assignments *
`media_buy_ids`	string[]	Filter by media buy assignments *
`unassigned`	boolean	Filter for unassigned creatives *
`has_served`	boolean	Filter for creatives that have served at least one impression *

* Assignment-related filters are specific to sales agents. Standalone creative agents ignore these.

Archived creatives are excluded by default. To include archived creatives in results, explicitly include "archived" in the statuses array.

Sorting options

Sort results by various fields with ascending or descending order:

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

Available sort fields:

created_date - When the creative was created (default)
updated_date - When creative was last modified
name - Creative name (alphabetical)
status - Approval status
assignment_count - Number of package assignments

Pagination

Control result set size with cursor-based pagination:

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

Response format

Schema: creative/list-creatives-response.json The response provides creative data with optional enrichment:

{
  "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
  }
}

Per-creative fields

Field	Type	Description
`creative_id`	string	Unique creative identifier
`name`	string	Human-readable name
`format_id`	object	Structured format reference
`status`	string	Approval status
`created_date`	string	Creation timestamp
`updated_date`	string	Last modified timestamp
`assets`	object	Creative assets (images, text, URLs, etc.)
`tags`	string[]	Tags for categorization
`concept_id`	string	Creative concept ID
`concept_name`	string	Human-readable concept name
`variables`	array	DCO variable definitions (when `include_variables=true`)
`assignments`	object	Package assignments (when `include_assignments=true`)
`snapshot`	object	Delivery snapshot (when `include_snapshot=true`)
`snapshot_unavailable_reason`	string	Why snapshot is missing — `SNAPSHOT_UNSUPPORTED`, `SNAPSHOT_TEMPORARILY_UNAVAILABLE`, or `SNAPSHOT_PERMISSION_DENIED`
`items`	array	Items for multi-asset formats (when `include_items=true`)

Delivery snapshot

When include_snapshot=true, each creative includes a lightweight delivery snapshot for operational questions like “is this creative active?” or “when did it last serve?” This is not analytics — for detailed performance data, use get_creative_delivery.

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

Field	Type	Required	Description
`as_of`	date-time	Yes	When this snapshot was captured
`staleness_seconds`	integer	Yes	Maximum age of data in seconds
`impressions`	integer	Yes	Lifetime impressions (not scoped to any date range)
`last_served`	date-time	No	Last time this creative served. Absent when it has never served.

Account requirements

Creative agents that host a library should implement the accounts protocol (sync_accounts / list_accounts) so buyers can establish access before querying creatives. This is the same accounts protocol used by sales agents for media buys — there is no separate version. Sales agents that already implement the accounts protocol for media buys do not need to do anything additional.

Examples

Concept-scoped query with variables

List all approved creatives in a specific concept, including DCO variable definitions:

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

Format-specific query

Find creatives matching specific format IDs across concepts:

{
  "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"]
  }
}

Find DCO creatives

Find creatives with dynamic content variables for personalized campaigns:

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

Field-limited query

Get minimal creative data for a selection dropdown:

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

Library health check

Find active creatives with delivery snapshots to identify stale or dormant assets:

{
  "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 - Detailed performance analytics with date ranges, variant breakdowns, and full delivery metrics
build_creative - Build manifests from library creatives or generate from scratch
sync_creatives - Upload and manage creative assets on any agent hosting a creative library
list_creative_formats - Discover supported creative formats
preview_creative - Generate previews of creative manifests

Documentation

​Overview

​Request parameters

​Core parameters

​Data inclusion options

​Filtering options

​Sorting options

​Pagination

​Response format

​Per-creative fields

​Delivery snapshot

​Account requirements

​Examples

​Concept-scoped query with variables

​Format-specific query

​Find DCO creatives

​Field-limited query

​Library health check

​Related tasks

Overview

Request parameters

Core parameters

Data inclusion options

Filtering options

Sorting options

Pagination

Response format

Per-creative fields

Delivery snapshot

Account requirements

Examples

Concept-scoped query with variables

Format-specific query

Find DCO creatives

Field-limited query

Library health check

Related tasks