{ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/media-buy/get-media-buy-delivery-response.json", "title": "Get Media Buy Delivery Response", "description": "Response payload for get_media_buy_delivery task", "type": "object", "allOf": [ { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/version-envelope.json" }, { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/protocol-envelope.json" } ], "properties": { "notification_type": { "type": "string", "enum": [ "scheduled", "final", "delayed", "adjusted", "window_update" ], "description": "Type of webhook notification (only present in webhook deliveries): scheduled = regular periodic update, final = campaign completed, delayed = data not yet available, adjusted = resending period with corrected data (same window), window_update = resending period with a wider measurement window (e.g., C3 superseding live, C7 superseding C3)" }, "partial_data": { "type": "boolean", "description": "Indicates if any media buys in this webhook have missing/delayed data (only present in webhook deliveries)" }, "unavailable_count": { "type": "integer", "minimum": 0, "description": "Number of media buys with reporting_delayed or failed status (only present in webhook deliveries when partial_data is true)" }, "sequence_number": { "type": "integer", "minimum": 1, "description": "Sequential notification number (only present in webhook deliveries, starts at 1)" }, "next_expected_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp for next expected notification (only present in webhook deliveries when notification_type is not 'final')" }, "reporting_period": { "type": "object", "description": "Half-open date range for the report: start is inclusive and end is exclusive. All periods use UTC timezone.", "properties": { "start": { "type": "string", "format": "date-time", "description": "ISO 8601 start timestamp in UTC (e.g., 2024-02-05T00:00:00Z)" }, "end": { "type": "string", "format": "date-time", "description": "Exclusive ISO 8601 end timestamp in UTC (e.g., 2024-02-06T00:00:00Z for a report covering 2024-02-05)" } }, "required": [ "start", "end" ], "additionalProperties": true }, "currency": { "type": "string", "description": "ISO 4217 currency code", "pattern": "^[A-Z]{3}$" }, "attribution_window": { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/attribution-window.json", "description": "Attribution methodology and lookback windows used for conversion metrics in this response. All media buys from a single seller share the same attribution methodology. Enables cross-platform comparison (e.g., Amazon 14-day click vs. Criteo 30-day click)." }, "aggregated_totals": { "type": "object", "description": "Combined metrics across all returned media buys. Only included in API responses (get_media_buy_delivery), not in webhook notifications.", "properties": { "impressions": { "type": "number", "description": "Total impressions delivered across all media buys", "minimum": 0 }, "spend": { "type": "number", "description": "Total amount spent across all media buys", "minimum": 0 }, "clicks": { "type": "number", "description": "Total clicks across all media buys (if applicable)", "minimum": 0 }, "completed_views": { "type": "number", "description": "Total audio/video completions across all media buys (if applicable)", "minimum": 0 }, "views": { "type": "number", "description": "Total views across all media buys (if applicable)", "minimum": 0 }, "conversions": { "type": "number", "description": "Total conversions across all media buys (if applicable)", "minimum": 0 }, "conversion_value": { "type": "number", "description": "Total conversion value across all media buys (if applicable)", "minimum": 0 }, "commissionable_value": { "type": "number", "description": "Total settled conversion value eligible for revenue-share commission across all media buys (if applicable)", "minimum": 0 }, "roas": { "type": "number", "description": "Aggregate return on ad spend across all media buys (total conversion_value / total spend)", "minimum": 0 }, "new_to_brand_rate": { "type": "number", "description": "Fraction of total conversions across all media buys from first-time brand buyers (weighted by conversion volume, not a simple average of per-buy rates)", "minimum": 0, "maximum": 1 }, "cost_per_acquisition": { "type": "number", "description": "Aggregate cost per conversion across all media buys (total spend / total conversions)", "minimum": 0 }, "completion_rate": { "type": [ "number", "null" ], "description": "Aggregate completion rate across all media buys (weighted by impressions, not a simple average of per-buy rates). Null indicates the metric is not applicable to the aggregated buys (e.g. all non-video inventory).", "minimum": 0, "maximum": 1 }, "reach": { "type": "number", "description": "Deduplicated reach across all media buys (if the seller can deduplicate across buys; otherwise sum of per-buy reach). Only present when all media buys share the same reach_unit. Omitted when reach units are heterogeneous — use per-buy reach values instead.", "minimum": 0 }, "reach_unit": { "allOf": [ { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/enums/reach-unit.json" } ], "description": "Unit of measurement for reach. Only present when all aggregated media buys use the same reach_unit." }, "frequency": { "type": "number", "description": "Average frequency per reach unit across all media buys (impressions / reach when cross-buy deduplication is available). Only present when reach is present.", "minimum": 0 }, "media_buy_count": { "type": "integer", "description": "Number of media buys included in the response", "minimum": 0 }, "metric_aggregates": { "type": "array", "description": "Cross-buy delivery aggregates partitioned by qualifier. Row-symmetric with `package.committed_metrics` and `by_package[].missing_metrics` — same atomic unit `(scope, metric_id, qualifier)` — so reconciliation collapses to a row-level join on the tuple. Granularity rule: one row per `(metric_id, full-qualifier-set)`, reported at the finest available granularity; buyers re-aggregate up if they want a coarser view. Used only for metrics with non-empty qualifier sets — unqualified metrics (`impressions`, `spend`, `media_buy_count`, etc.) remain at the top of `aggregated_totals`. **Mutual exclusion MUST**: for any `metric_id` appearing in `metric_aggregates`, the corresponding top-level scalar in `aggregated_totals` MUST be omitted (not zeroed) — avoids duplicate sources of truth. The qualifier vocabulary on this delivery surface is closed today (`additionalProperties: false`, same content as `committed_metrics.qualifier`) but is expected to **diverge from contract qualifier in future minors** as transparency disclosures buyers don't commit to ship delivery-only (e.g., `tracker_firing` pending #3832 resolution). Each row carries a `value` plus inlined per-metric component fields (e.g., `measurable_impressions` and `viewable_impressions` for `viewable_rate`; `spend` and `conversions` for `cost_per_acquisition`). Per-buy `totals` keeps its flat shape — each buy is single-qualifier by definition; only the aggregate spans qualifiers. **Qualifier-set drift across reports**: when a campaign gains a new qualifier mid-flight (e.g., adds `tracker_firing` partitioning in week 2), prior periods' rows remain valid at their original granularity; buyers SHOULD NOT retroactively repartition.", "items": { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/delivery-metric-aggregate.json" }, "examples": [ [ { "scope": "standard", "metric_id": "viewable_rate", "qualifier": { "viewability_standard": "mrc" }, "value": 0.7286, "measurable_impressions": 700000, "viewable_impressions": 510000 }, { "scope": "standard", "metric_id": "viewable_rate", "qualifier": { "viewability_standard": "groupm" }, "value": 0.55, "measurable_impressions": 180000, "viewable_impressions": 99000 }, { "scope": "vendor", "vendor": { "domain": "attentionvendor.example" }, "metric_id": "attention_units", "qualifier": {}, "value": 4.2, "measurable_impressions": 800000 } ] ] } }, "required": [ "impressions", "spend", "media_buy_count" ], "additionalProperties": true }, "media_buy_deliveries": { "type": "array", "description": "Array of delivery data for media buys. When used in webhook notifications, may contain multiple media buys aggregated by publisher. When used in get_media_buy_delivery API responses, typically contains requested media buys.", "items": { "type": "object", "properties": { "media_buy_id": { "type": "string", "description": "Seller's media buy identifier", "x-entity": "media_buy" }, "status": { "type": "string", "description": "Current media buy status. Lifecycle states use the same taxonomy as media-buy-status (`pending_creatives`, `pending_start`, `active`, `paused`, `completed`, `rejected`, `canceled`). In webhook context, reporting_delayed indicates data temporarily unavailable. `pending` is accepted as a legacy alias for pending_start.", "enum": [ "pending_creatives", "pending_start", "pending", "active", "paused", "completed", "rejected", "canceled", "failed", "reporting_delayed" ] }, "expected_availability": { "type": "string", "format": "date-time", "description": "When delayed data is expected to be available (only present when status is reporting_delayed)" }, "is_adjusted": { "type": "boolean", "description": "Indicates this delivery contains updated data for a previously reported period. Buyer should replace previous period data with these totals." }, "is_final": { "type": "boolean", "description": "Whether this row's delivery data is final for the reporting period. The row does not carry its own `measurement_window` — that lives on each `by_package[*]` entry. Reconciliation joins on per-package `measurement_window`; this row-level flag is a convenience roll-up. Sellers MUST NOT emit `is_final: true` at the row level unless every entry in `by_package` has `is_final: true` for the same `measurement_window` as the buy's `measurement_terms.billing_measurement.measurement_window` (or for the row's natural window when no `billing_measurement.measurement_window` is set). On any disagreement between row-level and package-level finality, package-level is authoritative. When true, the seller considers these numbers closed and is willing to invoice on them subject to `measurement_terms.billing_measurement`. When false, numbers may still move as measurement matures (broadcast C3 → C7) or processing completes (IVT scrubbing, dedup). When absent, the seller does not distinguish provisional from final at the row level — consult per-package `is_final`." }, "finalized_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp at which this row became final. Present only when `is_final: true`. Anchors the buyer's reconciliation and (when later defined) dispute-window clocks against the buy's `measurement_terms.billing_measurement`. Computed as the latest `finalized_at` across the row's packages for the reconciliation window." }, "pricing_model": { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/enums/pricing-model.json", "description": "Pricing model used for this media buy" }, "pacing_index": { "type": "number", "description": "Aggregate media-buy delivery pace relative to the media-buy pacing plan (1.0 = on track, <1.0 = behind, >1.0 = ahead). This is the authoritative pacing signal for seller-optimized buys; package pacing indexes are subordinate diagnostics.", "minimum": 0 }, "totals": { "allOf": [ { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/delivery-metrics.json" }, { "type": "object", "description": "Aggregate metrics for this media buy across all packages", "properties": { "effective_rate": { "type": "number", "description": "Effective rate paid per unit based on pricing_model (e.g., actual CPM for 'cpm', actual cost per completed view for 'cpcv', actual cost per point for 'cpp')", "minimum": 0 } }, "required": [ "spend" ] } ] }, "by_package": { "type": "array", "description": "Metrics broken down by package", "items": { "allOf": [ { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/delivery-metrics.json" }, { "type": "object", "properties": { "package_id": { "type": "string", "description": "Seller's package identifier", "x-entity": "package" }, "pacing_index": { "type": "number", "description": "Package delivery pace relative to its package-level pacing plan (1.0 = on track, <1.0 = behind, >1.0 = ahead). In seller-optimized mode this is a subordinate diagnostic and may be absent when no package pacing preference exists.", "minimum": 0 }, "pricing_model": { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/enums/pricing-model.json", "description": "The pricing model used for this package (e.g., cpm, cpcv, cpp). Indicates how the package is billed and which metrics are most relevant for optimization." }, "rate": { "type": "number", "description": "The pricing rate for this package. For fixed-rate pricing, this is the agreed currency-denominated unit rate (e.g., CPM rate of 12.50 means $12.50 per 1,000 impressions). For auction-based pricing, this is the effective rate based on actual delivery. For revenue_share, this is the decimal commission rate (e.g., 0.04 means 4%) and is not itself currency-denominated.", "minimum": 0 }, "currency": { "type": "string", "description": "ISO 4217 currency code for this package's pricing rate and spend. For AdCP-authored media buys this MUST equal the media-buy currency. A different package currency may appear only when reporting a legacy or externally created buy whose original contract allowed mixed denominations.", "pattern": "^[A-Z]{3}$" }, "delivery_status": { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/enums/delivery-status.json", "description": "System-reported operational state of this package. Reflects actual delivery state independent of buyer pause control. 'not_delivering' means zero impressions were recorded for the entire reporting_period while the package was in-flight. Sellers SHOULD only report 'not_delivering' once the package's data is_final for the period — a provisional (is_final: false) zero may still be measurement catching up, not genuine non-delivery." }, "paused": { "type": "boolean", "description": "Whether this package is currently paused by the buyer" }, "is_final": { "type": "boolean", "description": "Whether this delivery data is final for the reporting period. When false, the data may be updated as measurement matures (e.g., broadcast C7 window accumulating DVR playback) or as processing completes (e.g., IVT filtering, deduplication). When true, the seller considers this data closed — no further updates for this period — and is willing to invoice on it subject to the buy's `measurement_terms.billing_measurement`. Absent means the seller does not distinguish provisional from final data." }, "finalized_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp at which this package's data became final. Present only when `is_final: true`. Anchors reconciliation and (when later defined) dispute-window clocks against the buy's `measurement_terms.billing_measurement.measurement_window`." }, "measurement_window": { "type": "string", "maxLength": 50, "description": "Which measurement window this data represents, referencing a window_id from the product's reporting_capabilities.measurement_windows. For broadcast: 'live', 'c3', 'c7'. When absent, the data is not windowed (standard digital reporting). When present with is_final: false, a later report for the same period will provide a wider window or more complete data.", "examples": [ "live", "c3", "c7" ] }, "supersedes_window": { "type": "string", "maxLength": 50, "description": "Which measurement window this data replaces. Present on window_update notifications to indicate progression (e.g., 'live' when reporting C3 data that supersedes live-only numbers). Absent on the first report for a period. Buyers should replace stored data for the superseded window with this report's data.", "examples": [ "live", "c3" ] }, "missing_metrics": { "type": "array", "description": "Metrics that the binding reporting contract declared but that are NOT populated in this report. Reconciliation source: when `package.committed_metrics` is present, `missing_metrics` is computed against entries where `committed_at < reporting_period.end` — independent of subsequent product mutations and respecting the commitment timestamp on each entry (a metric committed mid-flight is only flagged missing in reports for periods after its commitment). When `package.committed_metrics` is absent, fall back to the product's current `reporting_capabilities.available_metrics` (no timestamp filter). Empty array (or absent) indicates clean delivery against the contract. Non-empty signals an accountability breach — the seller committed to the metric but did not produce the value here. Sellers MUST exclude metrics that are not yet measurable for the current `measurement_window` (e.g., post-IVT counts during the live window) — those will appear (or not) when a wider window supersedes this report via `supersedes_window`. Each entry uses an explicit `scope` discriminator: `standard` for entries from the closed `available-metric.json` enum, `vendor` for vendor-defined metrics anchored on a BrandRef. Symmetric with `committed_metrics`.", "items": { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/missing-metric.json" }, "examples": [ [], [ { "scope": "standard", "metric_id": "completed_views" } ], [ { "scope": "standard", "metric_id": "completed_views" }, { "scope": "vendor", "vendor": { "domain": "attentionvendor.example" }, "metric_id": "attention_units" } ] ] }, "by_catalog_item": { "type": "array", "description": "Delivery by catalog item within this package. Available for catalog-driven packages when the seller supports item-level reporting.", "items": { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/catalog-item-delivery-metrics.json" } }, "by_creative": { "type": "array", "description": "Metrics broken down by creative within this package. Available when the seller supports creative-level reporting.", "items": { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/creative-delivery-metrics.json" } }, "by_keyword": { "type": "array", "description": "Metrics broken down by keyword within this package. One row per (keyword, match_type) pair — the same keyword with different match types appears as separate rows. Keyword-grain only: rows reflect aggregate performance of each targeted keyword, not individual search queries. Rows may not sum to package totals when a single impression is attributed to the triggering keyword only. Available for search and retail media packages when the seller supports keyword-level reporting.", "items": { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/keyword-delivery-metrics.json" } }, "by_geo": { "type": "array", "description": "Delivery by geographic area within this package. Available when the buyer requests geo breakdown via reporting_dimensions and the seller supports it. Each dimension's rows are independent slices that should sum to the package total.", "items": { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/geo-delivery-metrics.json" } }, "by_geo_truncated": { "type": "boolean", "description": "Whether by_geo was truncated due to the requested limit or a seller-imposed maximum. Sellers MUST return this flag whenever by_geo is present (false means the list is complete)." }, "by_device_type": { "type": "array", "description": "Delivery by device form factor within this package. Available when the buyer requests device_type breakdown via reporting_dimensions and the seller supports it.", "items": { "allOf": [ { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/delivery-metrics.json" }, { "type": "object", "properties": { "device_type": { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/enums/device-type.json", "description": "Device form factor (desktop, mobile, tablet, ctv, dooh, unknown)" } }, "required": [ "device_type", "impressions", "spend" ] } ] } }, "by_device_type_truncated": { "type": "boolean", "description": "Whether by_device_type was truncated. Sellers MUST return this flag whenever by_device_type is present (false means the list is complete)." }, "by_device_platform": { "type": "array", "description": "Delivery by operating system within this package. Available when the buyer requests device_platform breakdown via reporting_dimensions and the seller supports it. Useful for CTV campaigns where tvOS vs Roku OS vs Fire OS matters.", "items": { "allOf": [ { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/delivery-metrics.json" }, { "type": "object", "properties": { "device_platform": { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/enums/device-platform.json", "description": "Operating system platform" } }, "required": [ "device_platform", "impressions", "spend" ] } ] } }, "by_device_platform_truncated": { "type": "boolean", "description": "Whether by_device_platform was truncated. Sellers MUST return this flag whenever by_device_platform is present (false means the list is complete)." }, "by_audience": { "type": "array", "description": "Delivery by audience segment within this package. Available when the buyer requests audience breakdown via reporting_dimensions and the seller supports it. Only 'synced' audiences are directly targetable via the targeting overlay; other sources are informational.", "items": { "allOf": [ { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/delivery-metrics.json" }, { "type": "object", "properties": { "audience_id": { "type": "string", "description": "Audience segment identifier. For 'synced' source, matches audience_id from sync_audiences. For other sources, seller-defined.", "x-entity": "audience" }, "audience_source": { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/enums/audience-source.json", "description": "Origin of the audience segment (synced, platform, third_party, lookalike, retargeting, unknown)" }, "audience_name": { "type": "string", "description": "Human-readable audience segment name" } }, "required": [ "audience_id", "audience_source", "impressions", "spend" ] } ] } }, "by_audience_truncated": { "type": "boolean", "description": "Whether by_audience was truncated. Sellers MUST return this flag whenever by_audience is present (false means the list is complete)." }, "by_demographic": { "type": "array", "description": "Delivery by demographic within this package. Available when the buyer requests demographic breakdown and the product declares supports_demographic_breakdown. A free-form measurement code does not prove alignment with buyer targeting. When age is present it is the authoritative machine-comparable interval; for requested age_ranges, sellers MUST echo the exact requested interval and MUST NOT substitute a wider or narrower native bucket.", "items": { "allOf": [ { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/delivery-metrics.json" }, { "type": "object", "properties": { "demographic": { "type": "string", "minLength": 1, "pattern": "\\S", "description": "Demographic code in the declared system's notation (for example, P25-54 for Nielsen)." }, "demographic_system": { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/enums/demographic-system.json", "description": "Measurement system that defines the demographic code." }, "age": { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/demographic-age-range.json", "description": "Canonical age interval represented by this row. Required by protocol semantics for age ranges requested through reporting_dimensions.demographic.age_ranges and for intervals declared in the product's demographic reporting capability." } }, "required": [ "demographic", "demographic_system", "impressions", "spend" ] } ] } }, "by_demographic_truncated": { "type": "boolean", "description": "Whether non-suppressed by_demographic rows were truncated due to the requested limit or a seller-imposed maximum. Sellers MUST return this flag whenever by_demographic is present. False means every non-suppressed row is present; inspect by_demographic_suppressed separately before reconciling rows to package totals." }, "by_demographic_suppressed": { "type": "boolean", "description": "Whether one or more otherwise reportable demographic rows were omitted due to privacy, policy, or measurement thresholds. Sellers MUST return this flag whenever by_demographic is present. False means no rows were threshold-suppressed." }, "by_placement": { "type": "array", "description": "Delivery by placement within this package. Available when the buyer requests placement breakdown via reporting_dimensions and the seller supports it. Placement IDs reference the product's placements array.", "items": { "allOf": [ { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/delivery-metrics.json" }, { "type": "object", "properties": { "placement_id": { "type": "string", "description": "Placement identifier from the product's placements array", "x-entity": "placement" }, "placement_name": { "type": "string", "description": "Human-readable placement name" }, "publisher_domain": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$", "description": "Canonical publisher domain whose adagents.json namespace this placement belongs to, matching the `publisher_domain` on the product's `placements[]` entry that `placement_id` resolves to (see core/placement.json). Lets buyers attribute delivered impressions to a publisher namespace without re-fetching the product catalog — the common case for multi-publisher buys through a single sales agent. Sellers SHOULD emit it whenever the resolving product placement carries a publisher_domain (always true for `kind: publisher_ref`); sellers MAY omit it only for `seller_inline` placements in a legacy single-publisher context where the seller agent's own domain is the namespace. Single-valued: a placement resolves within exactly one publisher namespace (package-level attribution, where an ad-network product can span publishers, is a separate concern)." } }, "required": [ "placement_id", "impressions", "spend" ] } ] } }, "by_placement_truncated": { "type": "boolean", "description": "Whether by_placement was truncated. Sellers MUST return this flag whenever by_placement is present (false means the list is complete)." }, "by_spot": { "type": "array", "description": "Spot-level as-run airing records for broadcast TV, radio, or other scheduled inventory. Available when the buyer requests spot breakdown and the product declares supports_spot_breakdown. Sellers MUST order rows by aired_at ascending. The same spot_id is reused when a later package measurement_window adds or revises metrics. Network and station are optional so station-direct radio and network-level TV records use the same channel-neutral shape.", "items": { "allOf": [ { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/delivery-metrics.json" }, { "type": "object", "properties": { "spot_id": { "type": "string", "minLength": 1, "description": "Stable seller-scoped identifier for this scheduled spot occurrence. Reused across measurement-window updates and available to later preemption or makegood workflows. Distinct from creative_id.", "x-entity": "spot_airing" }, "aired_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the spot actually aired. Its presence proves an airing; it is not inferred from impressions." }, "network": { "type": "string", "minLength": 1, "description": "Optional network or syndicated service name, for example 'USA Network' or 'Westwood One'." }, "station": { "type": "string", "minLength": 1, "description": "Optional station identifier or call sign, for example 'WABC-TV' or 'WNYC-FM'." }, "daypart": { "type": "string", "minLength": 1, "description": "Optional seller-defined daypart label, for example 'prime_time' or 'morning_drive'." } }, "required": [ "spot_id", "aired_at" ] } ] } }, "by_spot_truncated": { "type": "boolean", "description": "Whether by_spot is incomplete because of the requested limit or a seller-imposed maximum. Sellers MUST return this flag whenever by_spot is present (false means the as-run log is complete for the requested reporting period)." }, "daily_breakdown": { "type": "array", "description": "Day-by-day delivery for this package. Only present when include_package_daily_breakdown is true in the request. Enables per-package pacing analysis and line-item monitoring.", "items": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date (YYYY-MM-DD)" }, "impressions": { "type": "number", "description": "Daily impressions for this package", "minimum": 0 }, "spend": { "type": "number", "description": "Daily spend for this package", "minimum": 0 }, "conversions": { "type": "number", "description": "Daily conversions for this package", "minimum": 0 }, "conversion_value": { "type": "number", "description": "Daily conversion value for this package", "minimum": 0 }, "commissionable_value": { "type": "number", "description": "Daily settled conversion value eligible for revenue-share commission for this package", "minimum": 0 }, "roas": { "type": "number", "description": "Daily return on ad spend (conversion_value / spend)", "minimum": 0 }, "new_to_brand_rate": { "type": "number", "description": "Daily fraction of conversions from first-time brand buyers (0 = none, 1 = all)", "minimum": 0, "maximum": 1 } }, "required": [ "date", "impressions", "spend" ], "additionalProperties": true } } }, "required": [ "package_id", "spend", "pricing_model", "rate", "currency" ] } ] } }, "windows": { "type": "array", "description": "Per-window delivery slices over the reporting period at the requested time_granularity. Only present when the request set time_granularity and include_window_breakdown: true. Each slice mirrors what reporting_webhook would have delivered for the same window — buyers who missed webhook fires can reconstruct identical data by reading this array. Slice rows are ordered by window_start ascending; consecutive rows are contiguous (each row's window_end equals the next row's window_start) and partition the requested date range at the chosen granularity. Sellers MUST exclude this field when time_granularity is omitted; when set, sellers MUST honor pulls at any granularity in reporting_capabilities.windowed_pull_granularities (otherwise return UNSUPPORTED_GRANULARITY). See snapshot-and-log Rule 4 for the two-paths-parity contract this surface anchors.", "items": { "type": "object", "properties": { "window_start": { "type": "string", "format": "date-time", "description": "ISO 8601 start of the window slice (inclusive). UTC." }, "window_end": { "type": "string", "format": "date-time", "description": "ISO 8601 end of the window slice (exclusive). The next row's window_start equals this value when slices are contiguous." }, "totals": { "allOf": [ { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/delivery-metrics.json" } ], "description": "Aggregate metrics for this window slice across all packages. Shape-aligned with reporting_webhook fire payloads at the same granularity." }, "by_package": { "type": "array", "description": "Per-package metrics for this window slice. Same shape as the parent media_buy_deliveries[].by_package row but scoped to the window. Sellers MAY omit when per-package window-level data is unavailable; when present, package_id values MUST match the parent by_package entries.", "items": { "allOf": [ { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/delivery-metrics.json" }, { "type": "object", "properties": { "package_id": { "type": "string", "description": "Seller's package identifier", "x-entity": "package" } }, "required": [ "package_id" ] } ] } }, "is_final": { "type": "boolean", "description": "Whether the slice data is final for this window. Same semantics as the per-package is_final flag — when false, a later read may return revised numbers for the same window as measurement matures (broadcast C3 → C7, post-IVT filtering, etc.)." }, "measurement_window": { "type": "string", "maxLength": 50, "description": "Which measurement-window stage this slice represents (e.g., 'live', 'c3', 'c7'), referencing a window_id from the product's reporting_capabilities.measurement_windows. Absent when the data is not phased." } }, "required": [ "window_start", "window_end", "totals" ] } }, "daily_breakdown": { "type": "array", "description": "Day-by-day delivery", "items": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date (YYYY-MM-DD)" }, "impressions": { "type": "number", "description": "Daily impressions", "minimum": 0 }, "spend": { "type": "number", "description": "Daily spend", "minimum": 0 }, "conversions": { "type": "number", "description": "Daily conversions", "minimum": 0 }, "conversion_value": { "type": "number", "description": "Daily conversion value", "minimum": 0 }, "commissionable_value": { "type": "number", "description": "Daily settled conversion value eligible for revenue-share commission", "minimum": 0 }, "roas": { "type": "number", "description": "Daily return on ad spend (conversion_value / spend)", "minimum": 0 }, "new_to_brand_rate": { "type": "number", "description": "Daily fraction of conversions from first-time brand buyers (0 = none, 1 = all)", "minimum": 0, "maximum": 1 } }, "required": [ "date", "impressions", "spend" ], "additionalProperties": true } } }, "required": [ "media_buy_id", "status", "totals", "by_package" ], "additionalProperties": true } }, "errors": { "type": "array", "description": "Task-specific errors and warnings (e.g., missing delivery data, reporting platform issues)", "items": { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/error.json" } }, "sandbox": { "type": "boolean", "description": "When true, this response contains simulated data from sandbox mode." }, "context": { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/context.json" }, "ext": { "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/ext.json" } }, "required": [ "reporting_period", "currency", "media_buy_deliveries" ], "additionalProperties": true }