> ## Documentation Index > Fetch the complete documentation index at: https://agenticadvertisingorg-feature-feedback.mintlify.site/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 `"delivery"` in its [creative agent capabilities](#capability-declaration) — whether that's a dedicated creative service or a [sales agent implementing the Creative Protocol](/dist/docs/3.1.0-rc.13/creative/sales-agent-creative-capabilities). **Request Schema**: [`/schemas/3.1.0-rc.13/creative/get-creative-delivery-request.json`](https://adcontextprotocol.org/schemas/3.1.0-rc.13/creative/get-creative-delivery-request.json) **Response Schema**: [`/schemas/3.1.0-rc.13/creative/get-creative-delivery-response.json`](https://adcontextprotocol.org/schemas/3.1.0-rc.13/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.1.0-rc.13/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_id` | 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.1.0-rc.13/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) | | `quartile_data` | Audio/video quartile completion data — object with `q1_views`, `q2_views`, `q3_views`, `q4_views` | | `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 | | `manifest` | (Optional) The rendered creative manifest — the actual output that was served, not the input assets. Contains format\_id and resolved assets. Not all platforms can provide manifests for every variant. | | `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. 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_id": { "agent_url": "https://creative.example.com", "id": "display_300x250" }, "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_id": { "agent_url": "https://creative.example.com", "id": "display_300x250" }, "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_id": { "agent_url": "https://creative.example.com", "id": "display_300x250_generative" }, "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_id": { "agent_url": "https://creative.example.com", "id": "display_728x90_generative" }, "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` 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` | 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.1.0-rc.13/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` 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 declare `"delivery"` in their `capabilities` array within `list_creative_formats` responses: ```json theme={null} { "creative_agents": [{ "agent_url": "https://ads.seller-example.com", "capabilities": ["validation", "assembly", "preview", "delivery"] }] } ``` Buyers discover this by calling `list_creative_formats` and checking the `creative_agents` array for agents with `"delivery"` in their capabilities. This applies to any agent implementing the Creative Protocol, including sales agents.