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 — whether that’s a dedicated creative service or a sales agent implementing the Creative Protocol.

Request Schema: /schemas/3.0.19/creative/get-creative-delivery-request.json Response Schema: /schemas/3.0.19/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
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)

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 (impressions, spend, clicks, ctr, etc.)

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:

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.

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