> ## Documentation Index > Fetch the complete documentation index at: https://docs.adcontextprotocol.org/llms.txt > Use this file to discover all available pages before exploring further. # get_creative_delivery > get_creative_delivery retrieves variant-level delivery data with manifests and performance metrics for generative and static creatives in AdCP. Retrieve creative delivery data including variant-level breakdowns with manifests and metrics. This task returns what variants were created from your creatives, what they looked like (via manifests), and how they performed. This is a Creative Protocol task. Call it on any agent that declares `"creative"` in `supported_protocols` and exposes the `get_creative_delivery` tool — whether that's a dedicated creative service or a [sales agent implementing the Creative Protocol](/dist/docs/3.2.0-beta.0/creative/sales-agent-creative-capabilities). **Request Schema**: [`/schemas/3.2.0-beta.0/creative/get-creative-delivery-request.json`](https://adcontextprotocol.org/schemas/3.2.0-beta.0/creative/get-creative-delivery-request.json) **Response Schema**: [`/schemas/3.2.0-beta.0/creative/get-creative-delivery-response.json`](https://adcontextprotocol.org/schemas/3.2.0-beta.0/creative/get-creative-delivery-response.json) ## Request Parameters At least one scoping filter (`media_buy_ids` or `creative_ids`) is required. | Parameter | Type | Required | Description | | --------------- | -------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account` | [account-ref](/dist/docs/3.2.0-beta.0/building/by-layer/L2/accounts-and-agents#account-references) | No | Account reference. Pass `{ "account_id": "..." }` or `{ "brand": {...}, "operator": "..." }` if the seller supports implicit resolution. Limits results to creatives within this account. | | `media_buy_ids` | string\[] | Yes\* | Filter to specific media buys by publisher ID | | `creative_ids` | string\[] | Yes\* | Filter to specific creatives by ID | | `start_date` | string | No | Start date for delivery period (YYYY-MM-DD, interpreted in the platform's reporting timezone) | | `end_date` | string | No | End date for delivery period (YYYY-MM-DD, interpreted in the platform's reporting timezone) | | `max_variants` | integer | No | Maximum variants to return per creative. Useful for generative creatives with large variant counts. | | `pagination` | object | No | Cursor-based pagination parameters (`max_results`, `cursor`) for the creatives array. When omitted, all matching creatives are returned. | \* At least one of `media_buy_ids` or `creative_ids` must be provided. ## Response | Field | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | | `account_id` | Account identifier (present when scoped to a specific account) | | `media_buy_id` | Seller's media buy identifier (present when request was scoped to a single buy) | | `currency` | ISO 4217 currency code for monetary values (e.g., 'USD', 'EUR') | | `reporting_period` | Date range with start/end timestamps and `timezone` (IANA identifier — platforms report in their native timezone) | | `creatives` | Array of creative delivery data with variant breakdowns | | `pagination` | (Optional) Pagination info with `max_results`, `cursor`, and `has_more`. Present when the request included pagination parameters. | ### Creative Object | Field | Description | | --------------- | -------------------------------------------------------------------------------------------------------------- | | `creative_id` | Creative identifier | | `media_buy_id` | Seller's media buy identifier (present when the request spanned multiple media buys) | | `format_kind` | Canonical format of this creative | | `totals` | Aggregate delivery metrics across all variants — see [Delivery metrics fields](#delivery-metrics-fields) below | | `variant_count` | Total number of variants (may exceed `variants` array length when `max_variants` is used) | | `variants` | Array of variant-level delivery data (empty if creative has no variants yet) | ### Delivery metrics fields Fields available on both `creative.totals` and each `variant` entry. Commonly-used subset — see the [delivery-metrics schema](https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/delivery-metrics.json) for the full list including incrementality, brand lift, and broadcast metrics. | Field | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `impressions` | Impressions delivered | | `spend` | Amount spent (in `currency`) | | `clicks` | Total clicks | | `ctr` | Click-through rate (clicks/impressions) | | `cpm` | Cost per thousand impressions ((spend/impressions) × 1000) | | `cost_per_click` | Cost per click (spend/clicks) | | `views` | Billable views — threshold varies by format and pricing model | | `completed_views` | Video/audio completions | | `completion_rate` | Completion rate (completed\_views/impressions); `null` when not applicable (e.g. a non-video buy) | | `quartile_data` | Audio/video quartile completion data — object with `q1_views`, `q2_views`, `q3_views`, `q4_views`; `null` when not applicable (e.g. a non-video buy) | | `reach` | Unique reach in units specified by `reach_unit`. Measurement window declared via `reach_window`; without it, do not sum across rows | | `reach_unit` | Unit of measurement for `reach`; required when `reach` is present | | `reach_window` | Window semantics for reach/frequency — object with `kind` (`cumulative` for uniques since campaign start, `period` for non-overlapping snapshot, `rolling` for trailing window) and `period` (Duration, required for `period` and `rolling`). Optional but strongly recommended whenever `reach` is present | | `frequency` | Average frequency per `reach_unit`, measured over `reach_window` | | `grps` | Gross Rating Points delivered (for CPP) | | `conversions` | Total attributed conversions; equals the sum of `by_event_type[].count` when present | | `conversion_value` | Total monetary value of attributed conversions | | `roas` | Return on ad spend (conversion\_value/spend) — see note below | | `cost_per_acquisition` | Cost per conversion (spend/conversions) — see note below | | `new_to_brand_rate` | Fraction of conversions from first-time brand buyers (0–1) | | `leads` | Leads generated (convenience alias for `by_event_type` where `event_type='lead'`) | | `by_event_type` | Conversions by event type — array of `{ event_type, count, value?, event_source_id? }` | | `by_action_source` | Conversions by action source (website, app, in\_store) — array of `{ action_source, count, value?, event_source_id? }` | | `dooh_metrics` | DOOH-specific data — object with `loop_plays`, `screens_used`, `screen_time_seconds`, `sov_achieved`, `venue_breakdown` | | `viewability` | Viewability data — object with `vendor`, `measurable_impressions`, `viewable_impressions`, `viewable_rate`, `viewed_seconds` (average in-view duration per measurable impression — pairs with the `viewed_seconds` optimization goal), and `standard`. `standard` SHOULD be present whenever measured viewability values are reported | | `engagements` | Total ad engagements beyond viewing (platform-specific) | | `follows` | New followers or subscriptions attributed to delivery | | `saves` | Saves, bookmarks, or pins attributed to delivery | | `profile_visits` | In-platform page visits attributed to delivery | | `engagement_rate` | Platform-specific engagement rate (engagements/impressions) | | `vendor_metric_values` | Vendor-attested metrics (viewability, attention, etc.) — one entry per vendor and metric identifier | > **Spend-derived metrics.** Sellers should not populate `roas` and `cost_per_acquisition` on individual `variant` objects — spend cannot be attributed per-variant since it applies to the creative as a whole. These fields are meaningful only on `creative.totals`. `by_event_type` entries carry `count` and `value` per event type, but not spend-derived rates. > **Platform-conditional fields.** `dooh_metrics` is present only for DOOH campaigns. Engagement fields (`engagements`, `follows`, `saves`, `profile_visits`, `engagement_rate`) are platform-specific; not all sellers emit them on standardized fields — some use `variant.ext` for engagement data instead. ### Variant Object Each variant represents a specific execution: a fixed creative (Tier 1), an asset combination the platform selected (Tier 2), or a generated variant (Tier 3). For catalog-driven packages, each catalog item rendered as a distinct ad execution is a variant — the variant's manifest includes the catalog reference with the specific item rendered. | Field | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `variant_id` | Platform-assigned variant identifier | | `locale_variant_id` | Buyer-assigned localized variant that supplied the served assets. Required for delivered variants of a localized creative, including default fallback; omitted for unlocalized creatives. | | `manifest` | (Optional) The rendered canonical creative manifest—the actual output served, with `format_kind` and resolved assets. | | `generation_context` | (Optional, Tier 3) Input signals that triggered generation — e.g., page topic, conversation theme, query category. Platforms provide summarized/anonymized signals, not raw user input. When content context is managed through AdCP content standards, includes an `artifact` reference linking to the specific content artifact. Supports `ext` for vendor-specific context structures. | | `ext` | (Optional) Platform-specific data. Social platforms use this for engagement metrics (upvotes, comments, shares) that vary by platform. | | Standard metrics | All [Delivery metrics fields](#delivery-metrics-fields) — same shape as `creative.totals` | `creative_id` and `variant_id` are separate namespaces. The canonical build-to-delivery join is `build_creative.variants[].build_variant_id` → promoted `creative_id` → delivery `creative_id`. `variant_id` remains the platform's served execution variant id. ### Localized delivery attribution For a localized creative, every returned execution MUST include `locale_variant_id` and that value MUST exist in the creative's authoritative `list_creatives.localization.variants[]` set. This identifies the assets that actually served after strict RFC 4647 Lookup, an explicit locale fallback, or the default action and is required for every such path. When the selected product format carries `locale_policy`, this value MUST also identify a variant eligible under its accepted language ranges; buyer fallbacks and defaults never bypass that seller constraint. `variant_id` remains the seller execution identity; `locale_variant_id` is the buyer's stable locale identity. Derived metrics like `ctr`, `completion_rate`, `roas`, and `cost_per_click` are platform-calculated and may not equal naive division of their component fields due to rounding, attribution windows, or filtered impressions. ## Tier Behavior ### Tier 1: Standard Creatives One creative maps 1:1 to one variant. The variant metrics match the creative totals. ```json theme={null} { "media_buy_id": "mb_12345", "currency": "USD", "reporting_period": { "start": "2026-01-20T00:00:00-05:00", "end": "2026-01-27T23:59:59-05:00", "timezone": "America/New_York" }, "creatives": [ { "creative_id": "hero_video_30s", "totals": { "impressions": 150000, "spend": 7500, "clicks": 4500, "ctr": 0.03, "completion_rate": 0.72 }, "variants": [ { "variant_id": "hero_video_30s", "impressions": 150000, "spend": 7500, "clicks": 4500, "ctr": 0.03, "completion_rate": 0.72 } ] } ] } ``` ### Platform engagement metrics Social and feed-native platforms include engagement data in the `ext` field on each variant, since engagement types vary by platform: ```json theme={null} { "variant_id": "promoted_post_running_community", "impressions": 85000, "spend": 4250, "clicks": 2550, "ctr": 0.03, "ext": { "upvotes": 1240, "comments": 87, "shares": 34, "saves": 156, "comment_sentiment": "positive" } } ``` The `ext` field is not standardized across platforms — each platform defines its own engagement schema. Buyers aggregating across social platforms should map platform-specific fields to a common model. ### Tier 2: Asset Group Optimization Buyer provides multiple asset alternatives using a format with `selection_mode: "optimize"`. Platform tests combinations and returns the manifest for each variant showing which assets were selected. ```json theme={null} { "media_buy_id": "mb_12345", "currency": "USD", "reporting_period": { "start": "2026-01-20T00:00:00-05:00", "end": "2026-01-27T23:59:59-05:00", "timezone": "America/New_York" }, "creatives": [ { "creative_id": "summer_campaign_assets", "totals": { "impressions": 200000, "spend": 10000, "clicks": 8000, "ctr": 0.04 }, "variants": [ { "variant_id": "var_headline_a_image_c", "manifest": { "format_kind": "image", "assets": { "headline_0_text": { "asset_type": "text", "content": "Summer Sale - 50% Off" }, "image_0_url": { "asset_type": "image", "url": "https://cdn.brand.com/beach_hero.jpg", "width": 300, "height": 250 } } }, "impressions": 120000, "spend": 6000, "clicks": 6000, "ctr": 0.05 }, { "variant_id": "var_headline_b_image_d", "manifest": { "format_kind": "image", "assets": { "headline_0_text": { "asset_type": "text", "content": "Shop Summer Styles" }, "image_0_url": { "asset_type": "image", "url": "https://cdn.brand.com/sunset_hero.jpg", "width": 300, "height": 250 } } }, "impressions": 80000, "spend": 4000, "clicks": 2000, "ctr": 0.025 } ] } ] } ``` ### Tier 3: Generative Creative Platform generates variants from brand manifest and input contexts. The `manifest` contains the generated assets — which may differ entirely from what the buyer submitted. When the publisher uses AdCP content standards, `generation_context` can include an `artifact` reference linking the variant to the specific content (article, video, etc.) that triggered generation. Platforms can also use `ext` for vendor-specific context structures. ```json theme={null} { "media_buy_id": "mb_12345", "currency": "USD", "reporting_period": { "start": "2026-01-20T00:00:00-05:00", "end": "2026-01-27T23:59:59-05:00", "timezone": "America/New_York" }, "creatives": [ { "creative_id": "generative_banner", "totals": { "impressions": 300000, "spend": 15000, "clicks": 12000, "ctr": 0.04 }, "variants": [ { "variant_id": "gen_mobile_morning", "generation_context": { "context_type": "web_page", "artifact": { "property_id": { "type": "domain", "value": "techreview.example.com" }, "artifact_id": "article_semiconductor_trends_2026" }, "topic": "technology, semiconductors", "device_class": "mobile" }, "manifest": { "format_kind": "image", "assets": { "hero_image": { "asset_type": "image", "url": "https://cdn.creative.example.com/generated/mobile_morning_v1.jpg", "width": 300, "height": 250 }, "headline": { "asset_type": "text", "content": "Start Your Summer Right" } } }, "impressions": 180000, "spend": 9000, "clicks": 9000, "ctr": 0.05 }, { "variant_id": "gen_desktop_evening", "generation_context": { "context_type": "web_page", "topic": "lifestyle, evening entertainment", "device_class": "desktop" }, "manifest": { "format_kind": "image", "assets": { "hero_image": { "asset_type": "image", "url": "https://cdn.creative.example.com/generated/desktop_evening_v1.jpg", "width": 728, "height": 90 }, "headline": { "asset_type": "text", "content": "Evening Deals Await" } } }, "impressions": 120000, "spend": 6000, "clicks": 3000, "ctr": 0.025 } ] } ] } ``` ## Previewing Variants Use [`preview_creative`](/dist/docs/3.2.0-beta.0/creative/task-reference/preview_creative) with `request_type: "variant"` to see what a specific variant looked like when served: ```json theme={null} { "request_type": "variant", "variant_id": "gen_mobile_morning" } ``` Since each variant includes its full `manifest`, you can also pass the manifest directly to `preview_creative` as a standard single request to re-render it. ## Relationship to delivery reporting | Task | Protocol | What it provides | | --------------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------- | | [`get_media_buy_delivery`](/dist/docs/3.2.0-beta.0/media-buy/task-reference/get_media_buy_delivery) | Media Buy | WHERE and HOW MUCH: impressions, spend, placement data, optional `by_creative` breakdown | | `get_creative_delivery` | Creative | WHAT RAN and HOW: variant manifests and variant-level metrics | Use `media_buy_id` + `creative_id` as join keys to correlate data across both responses. When a sales agent implements both protocols, both tasks are available on the same agent URL. See [Creative capabilities on sales agents](/dist/docs/3.2.0-beta.0/creative/sales-agent-creative-capabilities) for the full pattern. ## Cross-agent aggregation When running campaigns across multiple sellers, call `get_creative_delivery` on each agent separately and correlate results: * **Join key**: Use `creative_id` (buyer-assigned) to correlate the same creative across agents. If you used `concept_id` during upload, filter by concept to group related creatives. * **`variant_id` scope**: Variant IDs are unique within an agent and creative, not globally. Two agents may generate variants with the same `variant_id` value. Prefix with the agent URL when building aggregated dashboards. * **Timezone handling**: Each agent may report in its own timezone via `reporting_period.timezone`. Normalize to a common timezone before aggregating metrics. * **`max_variants` selection**: Agents choose which variants to return when `max_variants` limits the result set. Most agents prioritize by impression volume (most-served first). For representative sampling, make multiple calls with different time ranges rather than relying on a single large `max_variants` value. ## Building a cross-agent dashboard When aggregating delivery data from multiple agents into a unified view, follow this sequence: 1. **Collect**: Call `get_creative_delivery` on each agent in parallel, using the same `creative_ids` filter. 2. **Normalize timezones**: Convert each agent's `reporting_period` to a common timezone before summing. 3. **Merge by `creative_id`**: Group results by `creative_id` across agents. Sum `totals` (impressions, spend, clicks). Do not average derived metrics like `ctr` — recompute them from the summed components. 4. **Prefix `variant_id`**: Create globally unique variant keys by combining `agent_url + variant_id` (e.g., `https://sales.pinnaclemedia-example.com/var_a1b2c3`). This prevents collisions when two agents assign the same variant ID independently. 5. **Group by `concept_id`**: For campaign-level roll-ups, use `concept_id` to group related creatives across sizes and sellers. Pull the concept-to-creative mapping from [`list_creatives`](/dist/docs/3.2.0-beta.0/creative/task-reference/list_creatives) on each agent. ```javascript theme={null} // Pseudocode: aggregate delivery from 3 sellers const agents = [pinnacle, novaSports, streamhaus]; const results = await Promise.all( agents.map(agent => agent.getCreativeDelivery({ creative_ids: ['acme_holiday_300x250'], start_date: '2026-11-01', end_date: '2026-11-15', }) ) ); const merged = {}; for (const [i, result] of results.entries()) { if (result.errors) continue; // skip failed agents, retry later for (const creative of result.creatives) { const key = creative.creative_id; if (!merged[key]) merged[key] = { impressions: 0, spend: 0, clicks: 0, variants: [] }; merged[key].impressions += creative.totals.impressions; merged[key].spend += creative.totals.spend; merged[key].clicks += creative.totals.clicks || 0; for (const v of creative.variants || []) { merged[key].variants.push({ ...v, variant_id: `${agents[i].url}/${v.variant_id}`, // globally unique }); } } } // Recompute derived metrics for (const c of Object.values(merged)) { c.ctr = c.impressions > 0 ? c.clicks / c.impressions : 0; } ``` ## Capability declaration Agents that support this task expose `get_creative_delivery` in their tool surface and declare Creative Protocol support through [`get_adcp_capabilities`](/dist/docs/3.2.0-beta.0/protocol/get_adcp_capabilities): ```json theme={null} { "supported_protocols": ["creative"], "creative": { "has_creative_library": true } } ``` Buyers discover candidate creative agents through the registry, then confirm the live endpoint's tool and `get_adcp_capabilities` surfaces. This applies to any endpoint implementing the Creative Protocol, including a sales agent with creative capabilities.