AdCP — list_creatives

Browse and filter creatives in a creative library. Supports filtering by asset type, 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 asset type, 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
Find creatives with seller indicators such as package-scoped creative fatigue

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)
`assignment_projection`	string	No	`all` (default) returns active assignments; `matching` returns only assignments matching `filters.indicator_types` and requires that filter.
`assignment_limit`	integer	No	Maximum nested assignment rows per creative (default: 50, maximum: 200).
`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)
`include_pricing`	boolean	No	Include `pricing_options` on each creative (default: false). Requires `account`.
`include_purged`	boolean	No	Include soft-purged creative tombstones (default: false). See Purged tombstones.
`include_webhook_activity`	boolean	No	Include recent webhook fires per creative (default: false). See Webhook activity.
`webhook_activity_limit`	integer	No	Maximum `webhook_activity[]` records per creative when `include_webhook_activity: true` (default: 50, range 1–200).
`account`	AccountRef	No	Account reference for pricing. When provided with `include_pricing`, the agent returns `pricing_options` from this account’s rate card on each creative.
`fields`	array	No	Specific optional fields to return (omit for all fields). Every row still includes the released base envelope: `creative_id`, `name`, `status`, `created_date`, `updated_date`, and exactly one of `format_id` or `format_kind`. Optional selections include `"assignments"`, `"assets"`, `"pricing_options"`, and `"rights"` / `"rights_attestation_evaluations"`; selecting rights evaluations automatically includes `rights`.

Filtering options

The filters object supports these optional, composable filters:

Filter	Type	Description
`accounts`	AccountRef[]	Filter by owning accounts
`format_kinds`	CanonicalFormatKind[]	Filter by canonical format kinds
`format_ids`	FormatID[]	Deprecated named-format compatibility filter
`asset_types`	AssetContentType[]	Filter by asset types directly assigned to top-level creative asset slots; values within the array use OR logic
`statuses`	CreativeStatus[]	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 *
`indicator_types`	`IndicatorType[]`	Filter for creatives with at least one package assignment carrying any requested current indicator type. See the standard indicator catalog. *

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

Asset-type matching

asset_types matches a creative when at least one direct object value in the top-level creative.assets map has an exact asset_type value in the requested set. Multiple requested values use OR logic. Array-valued slots are not inspected, and matching does not recurse into nested asset fields such as cards[].media; broader traversal is deferred. All active filter fields compose with AND logic. For example, the following request returns published-post creatives that also match the requested canonical format kind; a creative satisfying only one condition is excluded:

{
  "filters": {
    "asset_types": ["published_post"],
    "format_kinds": ["native_in_feed"]
  }
}

For deterministic status and assignment filters, every returned creative MUST satisfy the supplied predicates: status MUST be a member of statuses, and a sales agent applying media_buy_ids MUST return only creatives with an assignment to at least one requested media buy. These predicates remain in force across every page and compose with each other and with all other active filters. A seller MUST NOT accept them and return the unfiltered library. A filtered request can validly return the same rows as an unfiltered request when every visible creative already matches. Conformance is established from status and assignment membership—not by requiring the two response payloads to differ. Standalone creative agents retain the documented exception for sales-agent-specific assignment filters. Use asset_types: ["published_post"] to find existing-published-post reference creatives across sellers without enumerating publisher-specific format options, or asset_types: ["zip"] to find HTML5 bundle archives. Values such as url, text, and image are common companion assets, so they often produce broad result sets when used alone. Agents that do not implement asset_types MUST ignore that field and apply all other active filters. They must not reject the request solely because the filter is unsupported. Because unsupported agents deliberately over-return, buyers that require an exact filtered result MUST retain a local fallback: request assets (or omit fields), traverse every page until pagination.has_more is false, and locally inspect the returned top-level asset objects. When a seller returns query_summary.filters_applied, buyers can verify that it includes asset_types; absence means the local fallback is required.

Archived creatives are excluded by default. To include archived creatives in results, explicitly include "archived" in the statuses array. Suspended creatives are not archived; include "suspended" when you specifically want recoverably offline creatives such as published-post references with expired authorization.

For published-post reference products, list_creatives is limited to the downstream publisher identities the seller is authorized to inspect. If a product requires a second platform connection such as publisher_identity and it is missing, the seller should return AUTHORIZATION_REQUIRED with error.details.missing_connections[]. It should not present list_creatives as global platform post search.

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_kind": "image",
      "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_kind`	string	Canonical format kind
`format_option_ref`	object	Optional exact publisher/product option reference
`format_id`	object	Deprecated 3.x named-format compatibility field
`status`	string	Approval status
`created_date`	string	Creation timestamp
`updated_date`	string	Last modified timestamp
`assets`	object	Creative assets (images, text, URLs, etc.)
`localization`	object	Exact materialized locale assets, buyer-assigned variant identities, and default/unmatched policy for localized creatives.
`localization_unavailable`	object	Fail-closed per-item errors and retryability when exact localization readback cannot be constructed. Mutually exclusive with `localization`.
`tags`	string[]	Tags for categorization
`rights`	array	Exact retained rights constraints and portable references. Presentation only; not proof of seller verification.
`rights_attestation_evaluations`	array	Seller-produced, freshness-bounded grant evaluations. Each reference must exactly match one reference in the returned `rights` array.
`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`)
`pricing_options`	VendorPricingOption[]	Pricing options for this creative (when `include_pricing=true` and `account` provided). Vendors may offer multiple options (volume tiers, context-specific rates, different models per product line). Same pattern as `get_signals` and `list_content_standards`.

Assignment indicators

Creative-library sellers that advertise list_creatives in media_buy.relationship_notifications.projection_tasks attach evaluated indicator state to assignments.assigned_packages[] and include media_buy_id plus approval_status on every row, including unknown rows. These fields mirror get_media_buys for the same relationship. A mixed publisher/placement outcome uses approval_status: "partially_approved" plus complete approval_scopes[]; the assignment webhook remains a compact invalidation and buyers reread these scopes. Each evaluated row includes indicator_types_evaluated, indicators_as_of, and indicators[]; omitted types remain unknown.

{
  "include_assignments": true,
  "filters": {
    "indicator_types": ["creative_fatigue"]
  },
  "fields": ["creative_id", "assignments"],
  "assignment_projection": "matching",
  "assignment_limit": 50,
  "pagination": {
    "max_results": 100
  }
}

This request limits optional payload to assignments while retaining each row’s released base envelope (creative_id, name, status, dates, and one format identity). assignment_count remains the total active relationship count; returned_assignment_count, optional matching_assignment_count, and assignments_truncated describe the bounded nested projection. When truncated, use get_media_buys as the complete repair path. The standard indicator shape intentionally contains no indicator ID, source envelope, lifecycle status, or sub-version. The responding seller is the source; AdCP defines the broad meaning of the type for the negotiated protocol release. Seller-specific scores, methodology, evaluation windows, and upstream attribution belong in ext. Omitted indicators means unknown. An empty array is evaluated-clear only for indicator_types_evaluated and declared coverage. Do not infer clearing from filtered/paginated disappearance; directly reread without indicator_types. See Indicators and Warnings.

Rights attestation readback

Selecting fields: ["rights_attestation_evaluations"] automatically includes creative_id and rights. Every evaluation’s {rights_id, content_digest, reference} must select exactly one retained constraint and one byte-for-byte equal attestation_refs entry. The evaluation array is complete rather than independently truncated: because rights has no item ceiling, neither does its evaluation readback. A verified result is reusable only when the seller retrieves the byte-identical result from its own local evaluation store keyed by (evaluated_by, reference_digest), for that exact unchanged grant, and only until valid_until. The evaluated_by string alone is not provenance; buyer-authored and foreign-seller readback fails closed. The result is not a serving authorization and does not replace use, country, time, package, or impression-cap checks. When the seller advertises media_buy.rights_attestations.requirement: "required", every applicable constraint on a serving-eligible creative needs at least one current verified result.

Localized creative readback

For a localized creative, top-level creative_id identifies the creative and localization is the authoritative locale-topology round trip. The localization object lists exactly one source plus every materialized target variant; source-only monolingual topology therefore contains one variant. It preserves the originating request’s exact source ID/locale, target ID/locale set, default ID, unmatched action, and any explicit locale fallback rules. Each entry returns complete resolved assets under its buyer-assigned locale_variant_id; no seller- or platform-assigned variant ID is required. The top-level creative status is the single review lifecycle for the complete locale set. Verifiers enforce unique locale and buyer locale-variant ID values, exactly one source role, a default ID that references one variant, unique fallback language ranges whose IDs reference stored variants, and equality between source readback assets and top-level creative assets. These rules are machine-readable in x-adcp-validation because draft-07 uniqueItems compares whole objects and cannot express uniqueness or reference integrity by property. This object is atomic. If the seller omits a requested locale, normalizes it to a different locale, or loses an asset or identity, the seller returns localization_unavailable instead of a partial localization object. The item remains in the current page and counts toward query_summary.returned and pagination. Buyers may use its base metadata but MUST NOT infer locale eligibility. Selecting fields: ["localization"] automatically includes the creative ID, status, assets, format identity, and unavailable state needed to interpret this result. At delivery, sellers apply strict RFC 4647 Lookup: progressively truncate the requested range and match only an equal seller-eligible canonical tag. A selected product or placement locale_policy first filters this readback with RFC 4647 Basic Filtering; it never mutates or removes the globally stored variants. When no variant matches for a preference, sellers apply the most-specific explicit locale_fallbacks rule for that preference before moving to the next one. When all preferences miss both paths, they follow unmatched_locale_action: serve default_locale_variant_id or do not serve. The ordered preference list itself comes from the seller’s serving environment; AdCP neither carries it here nor defines how browser, content, geography, user, app, or platform signals produce it or their precedence. The chosen locale_variant_id is reported by get_creative_delivery.

Pricing

When include_pricing=true and account is provided, each creative includes pricing_options from the account’s rate card:

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

The buyer passes the applied pricing_option_id (from the build_creative response) in report_usage for billing verification. Vendors may offer multiple options — volume/commitment tiers, context-specific rates (premium vs. standard placements), or entirely different pricing models for different product lines. This is the same pattern used by signals and content standards.

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.

Purged tombstones

When a creative is destroyed via creative.purged with purge_kind: soft, the seller retains a tombstone for 30 days from the purge timestamp. The tombstone surfaces on list_creatives only when the request sets include_purged: true:

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

The status field on a tombstone is frozen at its pre-purge value (in the example above, "approved" is what the creative was right before purge — not a current claim). Buyers MUST treat the creative as gone: assignments, serving operations, and delivery reads no longer apply. The presence of the purge block is the unambiguous signal. Hard-purged creatives (purge_kind: hard, used for legal erasure under GDPR Article 17 / CCPA / equivalent) retain no tombstone; the creative.purged webhook is the only signal. See the snapshot-and-log conforming-pairs catalog for the recovery exclusion.

Webhook activity

When include_webhook_activity: true, each returned creative carries a webhook_activity[] array of the most recent fires scoped to that creative — creative.status_changed, creative.purged, creative.assignment_changed, and assignment-level indicators.changed deliveries. This is the buyer’s debug surface for “did the publisher fire? did my endpoint receive it? was the retry trail clean?” — the same shape and contract as webhook_activity[] on get_media_buys. See Webhook activity log pattern for the full normative contract (retention, three-state presence, request-field conventions). To subscribe when the seller declares media_buy.relationship_notifications, register a notification_configs[] entry on the account via sync_accounts. The seller fires per-subscriber against each entry whose event_types[] includes the type. Indicator support itself may be poll-only; push-capable sellers may advertise indicators.changed and independently advertise creative.assignment_changed. Subscriptions are prospective, so establish a complete all-status or known-ID baseline through get_media_buys after activation. Dedupe later invalidations and reread get_media_buys rather than applying payload state; webhook_activity[] on this read is a bounded reverse projection and debug log, not proof of complete repair. Three-state presence applies:

Field omitted — seller does not surface webhook activity on this read.
[] — seller surfaces the field but no fires fall in the retention window for this creative.
Non-empty — actual records, most recent first, capped at webhook_activity_limit (max 200).

Correlate to your endpoint logs by idempotency_key. Each record’s notification_type discriminates the fire kind:

{
  "webhook_activity": [
    {
      "idempotency_key": "whk_01HW9D2T3VXQ5M7K9N1P3R5S7U",
      "notification_id": "cs_ft88201_2026_05_18a",
      "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
    }
  ]
}

Buyers diagnose “no fires arrived” by combining: (a) subscriber registration state on list_accounts.accounts[].notification_configs[] — is the right URL active with the right event_types[]? — and (b) seller capability declaration via get_adcp_capabilities — does the seller support the event types I subscribed to? Field omission on webhook_activity alone does not distinguish “seller doesn’t surface the log” from “no fires occurred.”

Buyer handler (end-to-end)

A buyer’s webhook handler for creative.status_changed correlates each fire with library state via creative_id, dedupes on idempotency_key, and re-reads list_creatives for the authoritative snapshot (per snapshot-and-log Rule 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();
}

Two pitfalls this handler avoids: (1) applying state from the webhook payload directly (ordering and re-emission make the payload non-authoritative); (2) skipping dedup (sellers retry on non-2xx and re-emit on missed-events warnings).

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 canonical image creatives across concepts:

{
  "filters": {
    "format_kinds": ["image"],
    "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_kind", "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
Canonical formats - Discover product, publisher, and creative-agent format declarations
preview_creative - Generate previews of creative manifests

Getting Started

Building with AdCP

Protocol

Using AAO

FAQ

Trust & Security

Reference

Certification

list_creatives

Overview

Request parameters

Core parameters

Data inclusion options

Filtering options

Asset-type matching

Sorting options

Response format

Per-creative fields

Assignment indicators

Rights attestation readback

Localized creative readback

Pricing

Delivery snapshot

Purged tombstones

Webhook activity

Buyer handler (end-to-end)

Account requirements

Examples

Concept-scoped query with variables

Format-specific query

Find DCO creatives

Field-limited query

Library health check

​Overview

​Request parameters

​Core parameters

​Data inclusion options

​Filtering options

​Asset-type matching

​Sorting options

​Pagination

​Response format

​Per-creative fields

​Assignment indicators

​Rights attestation readback

​Localized creative readback

​Pricing

​Delivery snapshot

​Purged tombstones

​Webhook activity

​Buyer handler (end-to-end)

​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

Asset-type matching

Sorting options

Pagination

Response format

Per-creative fields

Assignment indicators

Rights attestation readback

Localized creative readback

Pricing

Delivery snapshot

Purged tombstones

Webhook activity

Buyer handler (end-to-end)

Account requirements

Examples

Concept-scoped query with variables

Format-specific query

Find DCO creatives

Field-limited query

Library health check

Related tasks