AdCP — get_creative

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. Request Schema: /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

Request Parameters

At least one scoping filter (media_buy_ids or creative_ids) is required.

Parameter	Type	Required	Description
`account`	account-ref	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 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 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 — 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.

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

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

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

{
  "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 with request_type: "variant" to see what a specific variant looked like when served:

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

Collect: Call get_creative_delivery on each agent in parallel, using the same creative_ids filter.
Normalize timezones: Convert each agent’s reporting_period to a common timezone before summing.
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.
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.
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.

// 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:

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

Getting Started

Building with AdCP

Protocol

Using AAO

FAQ

Trust & Security

Reference

Certification

get_creative_delivery

Request Parameters

Response

Creative Object

Delivery metrics fields

Variant Object

Localized delivery attribution

Tier Behavior

Tier 1: Standard Creatives

Platform engagement metrics

Tier 2: Asset Group Optimization

Tier 3: Generative Creative

Previewing Variants

Relationship to delivery reporting

Cross-agent aggregation

Building a cross-agent dashboard

Capability declaration

​Request Parameters

​Response

​Creative Object

​Delivery metrics fields

​Variant Object

​Localized delivery attribution

​Tier Behavior

​Tier 1: Standard Creatives

​Platform engagement metrics

​Tier 2: Asset Group Optimization

​Tier 3: Generative Creative

​Previewing Variants

​Relationship to delivery reporting

​Cross-agent aggregation

​Building a cross-agent dashboard

​Capability declaration

Request Parameters

Response

Creative Object

Delivery metrics fields

Variant Object

Localized delivery attribution

Tier Behavior

Tier 1: Standard Creatives

Platform engagement metrics

Tier 2: Asset Group Optimization

Tier 3: Generative Creative

Previewing Variants

Relationship to delivery reporting

Cross-agent aggregation

Building a cross-agent dashboard

Capability declaration