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 "delivery" in its creative agent capabilities — whether that’s a dedicated creative service or a sales agent implementing the Creative Protocol. Request Schema: /schemas/v3/creative/get-creative-delivery-request.json Response Schema: /schemas/v3/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_id`	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)
`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`
`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 — same shape as `creative.totals`

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_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.

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

{
  "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 declare "delivery" in their capabilities array within list_creative_formats responses:

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

Documentation

Documentation Index

​Request Parameters

​Response

​Creative Object

​Delivery metrics fields

​Variant Object

​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