> ## Documentation Index
> Fetch the complete documentation index at: https://agenticadvertisingorg-snap-format-preview-links.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# list_creatives
> list_creatives browses and filters creatives in an AdCP library by format, status, concept, and tags with cursor-based pagination.
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`](https://adcontextprotocol.org/schemas/3.0.19/creative/list-creatives-request.json)
### Core parameters
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ------------------------------------------------------------------- |
| `filters` | object | No | Filter criteria — see [filtering options](#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`](/dist/docs/3.0.19/creative/task-reference/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`. |
| `account` | [AccountRef](/dist/docs/3.0.19/building/by-layer/L2/accounts-and-agents#account-references) | 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 fields to return (omit for all fields). Includes `"pricing_options"` for sparse selection. |
## Filtering options
The `filters` object supports these optional, composable filters:
| Filter | Type | Description |
| ---------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `accounts` | [AccountRef](/dist/docs/3.0.19/building/by-layer/L2/accounts-and-agents#account-references)\[] | Filter by owning accounts |
| `format_ids` | FormatID\[] | Filter by structured format IDs |
| `statuses` | [CreativeStatus](/dist/docs/3.0.19/creative/specification#creative-status-lifecycle)\[] | 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:
```json theme={null}
{
"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:
```json theme={null}
{
"pagination": {
"max_results": 50,
"cursor": "eyJjcmVhdGVkX2RhdGUiOi4uLn0"
}
}
```
## Response format
**Schema**: [`creative/list-creatives-response.json`](https://adcontextprotocol.org/schemas/3.0.19/creative/list-creatives-response.json)
The response provides creative data with optional enrichment:
```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
}
}
```
### 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`) |
| `pricing_options` | [VendorPricingOption](/dist/docs/3.0.19/creative/specification#pricing)\[] | 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`. |
### Pricing
When `include_pricing=true` and `account` is provided, each creative includes `pricing_options` from the account's rate card:
```json theme={null}
{
"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](/dist/docs/3.0.19/signals/tasks/get_signals) and [content standards](/dist/docs/3.0.19/governance/content-standards/index).
### 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`](/dist/docs/3.0.19/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"
}
}
```
| 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](/dist/docs/3.0.19/accounts/overview) (`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:
```json theme={null}
{
"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:
```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"]
}
}
```
### Find DCO creatives
Find creatives with dynamic content variables for personalized campaigns:
```json theme={null}
{
"filters": {
"has_variables": true,
"statuses": ["approved"]
},
"include_variables": true
}
```
### Field-limited query
Get minimal creative data for a selection dropdown:
```json theme={null}
{
"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:
```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"
}
}
```
## Related tasks
* [`get_creative_delivery`](/dist/docs/3.0.19/creative/task-reference/get_creative_delivery) - Detailed performance analytics with date ranges, variant breakdowns, and full delivery metrics
* [`build_creative`](/dist/docs/3.0.19/creative/task-reference/build_creative) - Build manifests from library creatives or generate from scratch
* [`sync_creatives`](/dist/docs/3.0.19/creative/task-reference/sync_creatives) - Upload and manage creative assets on any agent hosting a creative library
* [`list_creative_formats`](/dist/docs/3.0.19/creative/task-reference/list_creative_formats) - Discover supported creative formats
* [`preview_creative`](/dist/docs/3.0.19/creative/task-reference/preview_creative) - Generate previews of creative manifests