Interface GetMediaBuyDeliveryResponse

Response payload for get_media_buy_delivery task

interface GetMediaBuyDeliveryResponse {
    context_id?: string;
    context?: ContextObject;
    task_id?: string;
    status: TaskStatus;
    message?: string;
    timestamp?: string;
    replayed?: boolean;
    adcp_error?: Error;
    push_notification_config?: PushNotificationConfig;
    governance_context?: string;
    payload?: {};
    adcp_version?: string;
    adcp_major_version?: number;
    notification_type?:
        | "scheduled"
        | "final"
        | "delayed"
        | "adjusted"
        | "window_update";
    partial_data?: boolean;
    unavailable_count?: number;
    sequence_number?: number;
    next_expected_at?: string;
    reporting_period: { start: string; end: string };
    currency?: string;
    attribution_window?: AttributionWindow;
    aggregated_totals?: {
        impressions: number;
        spend: number;
        clicks?: number;
        completed_views?: number;
        views?: number;
        conversions?: number;
        conversion_value?: number;
        roas?: number;
        new_to_brand_rate?: number;
        cost_per_acquisition?: number;
        completion_rate?: number;
        reach?: number;
        reach_unit?: ReachUnit;
        frequency?: number;
        media_buy_count: number;
        metric_aggregates?: DeliveryMetricAggregate[];
    };
    media_buy_deliveries: {
        media_buy_id: string;
        status: | "active"
        | "rejected"
        | "pending_creatives"
        | "pending_start"
        | "paused"
        | "completed"
        | "canceled"
        | "pending"
        | "failed"
        | "reporting_delayed";
        expected_availability?: string;
        is_adjusted?: boolean;
        is_final?: boolean;
        finalized_at?: string;
        pricing_model?: PricingModel;
        totals: DeliveryMetrics & { effective_rate?: number };
        by_package: (
            DeliveryMetrics & {
                package_id: string;
                pacing_index?: number;
                pricing_model?: PricingModel;
                rate?: number;
                currency?: string;
                delivery_status?: | "completed"
                | "delivering"
                | "budget_exhausted"
                | "flight_ended"
                | "goal_met";
                paused?: boolean;
                is_final?: boolean;
                finalized_at?: string;
                measurement_window?: string;
                supersedes_window?: string;
                missing_metrics?: MissingMetric[];
                by_catalog_item?: CatalogItemDeliveryMetrics[];
                by_creative?: CreativeDeliveryMetrics[];
                by_keyword?: KeywordDeliveryMetrics[];
                by_geo?: GeoDeliveryMetrics[];
                by_geo_truncated?: boolean;
                by_device_type?: (DeliveryMetrics & { device_type?: DeviceType })[];
                by_device_type_truncated?: boolean;
                by_device_platform?: (
                    DeliveryMetrics & { device_platform?: DevicePlatform }
                )[];
                by_device_platform_truncated?: boolean;
                by_audience?: (
                    DeliveryMetrics & {
                        audience_id?: string;
                        audience_source?: AudienceSource;
                        audience_name?: string;
                    }
                )[];
                by_audience_truncated?: boolean;
                by_placement?: (
                    DeliveryMetrics & {
                        placement_id?: string;
                        placement_name?: string;
                        publisher_domain?: string;
                    }
                )[];
                by_placement_truncated?: boolean;
                daily_breakdown?: {
                    date: string;
                    impressions: number;
                    spend: number;
                    conversions?: number;
                    conversion_value?: number;
                    roas?: number;
                    new_to_brand_rate?: number;
                }[];
            }
        )[];
        windows?: {
            window_start: string;
            window_end: string;
            totals: DeliveryMetrics;
            by_package?: (DeliveryMetrics & { package_id: string })[];
            is_final?: boolean;
            measurement_window?: string;
        }[];
        daily_breakdown?: {
            date: string;
            impressions: number;
            spend: number;
            conversions?: number;
            conversion_value?: number;
            roas?: number;
            new_to_brand_rate?: number;
        }[];
    }[];
    errors?: Error[];
    sandbox?: boolean;
    ext?: ExtensionObject;
}

Properties

`Optional`context_id

context_id?: string

Session/conversation identifier for tracking related operations across multiple task invocations. Managed by the protocol layer to maintain conversational context. Distinct from context (per-request opaque echo, see below).

`Optional`context

context?: ContextObject

`Optional`task_id

task_id?: string

Unique identifier for tracking asynchronous operations. Present when a task requires extended processing time. Used to query task status and retrieve results when complete.

status

status: TaskStatus

`Optional`message

message?: string

Human-readable summary of the task result. Provides natural language explanation of what happened, suitable for display to end users or for AI agent comprehension. Generated by the protocol layer based on the task response.

`Optional`timestamp

timestamp?: string

ISO 8601 timestamp when the response was generated. Useful for debugging, logging, cache validation, and tracking async operation progress.

`Optional`replayed

replayed?: boolean

Set to true when this response was returned from the idempotency cache rather than from a fresh execution. Set to false (or omitted) when the request was executed fresh. Buyers use this to distinguish cached replays from new executions — matters for billing reconciliation, audit logs, state-machine routing (cached state-tracking fields are historical snapshots, not current state — re-read via the resource's read endpoint), and any downstream system that assumes exactly-once event semantics. From 3.1 onward, replayed MAY appear on responses to any request that resolved via the idempotency cache, including read tools — universal idempotency_key (see security.mdx §Idempotency) means the cache holds read responses too.

`Optional`adcp_error

adcp_error?: Error

`Optional`push_notification_config

push_notification_config?: PushNotificationConfig

`Optional`governance_context

governance_context?: string

Governance context token issued by the account's governance agent during check_governance. Buyers attach it to governed purchase requests (media buys, rights acquisitions, signal activations, creative services); sellers persist it and include it on all subsequent governance calls for that action's lifecycle. An account binds to one governance agent (see sync_governance); governance is phased across purchase / modification / delivery, not partitioned across specialist agents, so the envelope carries a single token for the full lifecycle.

Value format: governance agents MUST emit a compact JWS per the AdCP JWS profile (see Security — Signed Governance Context). Sellers MAY verify; sellers that do not verify MUST persist and forward the token unchanged. In 3.1 all sellers MUST verify. Non-JWS values from pre-3.0 governance agents are deprecated.

This is the primary correlation key for audit and reporting across the governance lifecycle.

`Optional`payload

payload?: {}

Conceptual grouping for the task-specific response data defined by individual task response schemas (e.g., get-products-response.json, create-media-buy-response.json). payload is a documentary construct — it is NOT a required wire field, and its on-the-wire shape depends on transport (see Transport serialization below). Task response schemas declare body fields without wrapping them in a payload object; the wire representation places those body fields per transport convention. On MCP the body fields appear as siblings of envelope fields at the root of the tool response; on A2A they appear inside task.artifacts[0].parts[].DataPart; on REST they appear at the root of the JSON body.

`Optional`adcp_version

adcp_version?: string

Release-precision AdCP version (VERSION.RELEASE, e.g. "3.0", "3.1", "3.1-beta"). On a request: the buyer's release pin — the seller validates against its supported_versions and returns VERSION_UNSUPPORTED on cross-major mismatch, or downshifts to the highest supported release within the same major. On a response: the release the seller actually served — clients SHOULD validate the response against that release's schema, not against their pin. Patches are not negotiated; surface them as build_version on capabilities for operational visibility. When omitted, falls back to adcp_major_version (deprecated) or server default. Buyers SHOULD emit both adcp_version and adcp_major_version through 3.x to remain compatible with sellers that only read the legacy field. NORMALIZATION: SDKs that read full-semver values from bundle metadata (e.g. ComplianceIndex.published_version = "3.1.0-beta.1") MUST normalize to release-precision ("3.1-beta.1") before emitting on the wire — meta-field values are NOT valid wire values.

`Optional`adcp_major_version

adcp_major_version?: number

DEPRECATED in favor of adcp_version (release-precision string). Servers MUST continue to honor this field through 3.x. Removed in 4.0. Original semantics: the AdCP major version the buyer's payloads conform to. Sellers validate against their supported major_versions and return VERSION_UNSUPPORTED if unsupported. When omitted, the seller assumes its highest supported version.

`Optional`notification_type

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)

`Optional`partial_data

partial_data?: boolean

Indicates if any media buys in this webhook have missing/delayed data (only present in webhook deliveries)

`Optional`unavailable_count

unavailable_count?: number

Number of media buys with reporting_delayed or failed status (only present in webhook deliveries when partial_data is true)

Minimum

`Optional`sequence_number

sequence_number?: number

Sequential notification number (only present in webhook deliveries, starts at 1)

Minimum

`Optional`next_expected_at

next_expected_at?: string

ISO 8601 timestamp for next expected notification (only present in webhook deliveries when notification_type is not 'final')

Format

date-time

reporting_period

reporting_period: { start: string; end: string }

Date range for the report. All periods use UTC timezone.

Type Declaration

start: string
ISO 8601 start timestamp in UTC (e.g., 2024-02-05T00:00:00Z)

Format
date-time
end: string
ISO 8601 end timestamp in UTC (e.g., 2024-02-05T23:59:59Z)

Format
date-time

`Optional`currency

currency?: string

ISO 4217 currency code

Pattern

^[A-Z]{3}$

`Optional`attribution_window

attribution_window?: AttributionWindow

`Optional`aggregated_totals

aggregated_totals?: {
    impressions: number;
    spend: number;
    clicks?: number;
    completed_views?: number;
    views?: number;
    conversions?: number;
    conversion_value?: number;
    roas?: number;
    new_to_brand_rate?: number;
    cost_per_acquisition?: number;
    completion_rate?: number;
    reach?: number;
    reach_unit?: ReachUnit;
    frequency?: number;
    media_buy_count: number;
    metric_aggregates?: DeliveryMetricAggregate[];
}

Combined metrics across all returned media buys. Only included in API responses (get_media_buy_delivery), not in webhook notifications.

Type Declaration

impressions: number
Total impressions delivered across all media buys

Minimum
0
spend: number
Total amount spent across all media buys

Minimum
0
Optionalclicks?: number
Total clicks across all media buys (if applicable)

Minimum
0
Optionalcompleted_views?: number
Total audio/video completions across all media buys (if applicable)

Minimum
0
Optionalviews?: number
Total views across all media buys (if applicable)

Minimum
0
Optionalconversions?: number
Total conversions across all media buys (if applicable)

Minimum
0
Optionalconversion_value?: number
Total conversion value across all media buys (if applicable)

Minimum
0
Optionalroas?: number
Aggregate return on ad spend across all media buys (total conversion_value / total spend)

Minimum
0
Optionalnew_to_brand_rate?: number
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
Optionalcost_per_acquisition?: number
Aggregate cost per conversion across all media buys (total spend / total conversions)

Minimum
0
Optionalcompletion_rate?: number
Aggregate completion rate across all media buys (weighted by impressions, not a simple average of per-buy rates)

Minimum
0

Maximum
1
Optionalreach?: number
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
Optionalreach_unit?: ReachUnit
Unit of measurement for reach. Only present when all aggregated media buys use the same reach_unit.
Optionalfrequency?: number
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: number
Number of media buys included in the response

Minimum
0
Optionalmetric_aggregates?: DeliveryMetricAggregate[]
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.

media_buy_deliveries

media_buy_deliveries: {
    media_buy_id: string;
    status:
        | "active"
        | "rejected"
        | "pending_creatives"
        | "pending_start"
        | "paused"
        | "completed"
        | "canceled"
        | "pending"
        | "failed"
        | "reporting_delayed";
    expected_availability?: string;
    is_adjusted?: boolean;
    is_final?: boolean;
    finalized_at?: string;
    pricing_model?: PricingModel;
    totals: DeliveryMetrics & { effective_rate?: number };
    by_package: (
        DeliveryMetrics & {
            package_id: string;
            pacing_index?: number;
            pricing_model?: PricingModel;
            rate?: number;
            currency?: string;
            delivery_status?: | "completed"
            | "delivering"
            | "budget_exhausted"
            | "flight_ended"
            | "goal_met";
            paused?: boolean;
            is_final?: boolean;
            finalized_at?: string;
            measurement_window?: string;
            supersedes_window?: string;
            missing_metrics?: MissingMetric[];
            by_catalog_item?: CatalogItemDeliveryMetrics[];
            by_creative?: CreativeDeliveryMetrics[];
            by_keyword?: KeywordDeliveryMetrics[];
            by_geo?: GeoDeliveryMetrics[];
            by_geo_truncated?: boolean;
            by_device_type?: (DeliveryMetrics & { device_type?: DeviceType })[];
            by_device_type_truncated?: boolean;
            by_device_platform?: (
                DeliveryMetrics & { device_platform?: DevicePlatform }
            )[];
            by_device_platform_truncated?: boolean;
            by_audience?: (
                DeliveryMetrics & {
                    audience_id?: string;
                    audience_source?: AudienceSource;
                    audience_name?: string;
                }
            )[];
            by_audience_truncated?: boolean;
            by_placement?: (
                DeliveryMetrics & {
                    placement_id?: string;
                    placement_name?: string;
                    publisher_domain?: string;
                }
            )[];
            by_placement_truncated?: boolean;
            daily_breakdown?: {
                date: string;
                impressions: number;
                spend: number;
                conversions?: number;
                conversion_value?: number;
                roas?: number;
                new_to_brand_rate?: number;
            }[];
        }
    )[];
    windows?: {
        window_start: string;
        window_end: string;
        totals: DeliveryMetrics;
        by_package?: (DeliveryMetrics & { package_id: string })[];
        is_final?: boolean;
        measurement_window?: string;
    }[];
    daily_breakdown?: {
        date: string;
        impressions: number;
        spend: number;
        conversions?: number;
        conversion_value?: number;
        roas?: number;
        new_to_brand_rate?: number;
    }[];
}[]

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.

Type Declaration

media_buy_id: string
Seller's media buy identifier
status:
    | "active"
    | "rejected"
    | "pending_creatives"
    | "pending_start"
    | "paused"
    | "completed"
    | "canceled"
    | "pending"
    | "failed"
    | "reporting_delayed"
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.
Optionalexpected_availability?: string
When delayed data is expected to be available (only present when status is reporting_delayed)

Format
date-time
Optionalis_adjusted?: boolean
Indicates this delivery contains updated data for a previously reported period. Buyer should replace previous period data with these totals.
Optionalis_final?: boolean
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.
Optionalfinalized_at?: string
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.

Format
date-time
Optionalpricing_model?: PricingModel
totals: DeliveryMetrics & { effective_rate?: number }
by_package: (
    DeliveryMetrics & {
        package_id: string;
        pacing_index?: number;
        pricing_model?: PricingModel;
        rate?: number;
        currency?: string;
        delivery_status?: | "completed"
        | "delivering"
        | "budget_exhausted"
        | "flight_ended"
        | "goal_met";
        paused?: boolean;
        is_final?: boolean;
        finalized_at?: string;
        measurement_window?: string;
        supersedes_window?: string;
        missing_metrics?: MissingMetric[];
        by_catalog_item?: CatalogItemDeliveryMetrics[];
        by_creative?: CreativeDeliveryMetrics[];
        by_keyword?: KeywordDeliveryMetrics[];
        by_geo?: GeoDeliveryMetrics[];
        by_geo_truncated?: boolean;
        by_device_type?: (DeliveryMetrics & { device_type?: DeviceType })[];
        by_device_type_truncated?: boolean;
        by_device_platform?: (
            DeliveryMetrics & { device_platform?: DevicePlatform }
        )[];
        by_device_platform_truncated?: boolean;
        by_audience?: (
            DeliveryMetrics & {
                audience_id?: string;
                audience_source?: AudienceSource;
                audience_name?: string;
            }
        )[];
        by_audience_truncated?: boolean;
        by_placement?: (
            DeliveryMetrics & {
                placement_id?: string;
                placement_name?: string;
                publisher_domain?: string;
            }
        )[];
        by_placement_truncated?: boolean;
        daily_breakdown?: {
            date: string;
            impressions: number;
            spend: number;
            conversions?: number;
            conversion_value?: number;
            roas?: number;
            new_to_brand_rate?: number;
        }[];
    }
)[]
Metrics broken down by package
Optionalwindows?: {
    window_start: string;
    window_end: string;
    totals: DeliveryMetrics;
    by_package?: (DeliveryMetrics & { package_id: string })[];
    is_final?: boolean;
    measurement_window?: string;
}[]
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.
Optionaldaily_breakdown?: {
    date: string;
    impressions: number;
    spend: number;
    conversions?: number;
    conversion_value?: number;
    roas?: number;
    new_to_brand_rate?: number;
}[]
Day-by-day delivery

`Optional`errors

errors?: Error[]

Task-specific errors and warnings (e.g., missing delivery data, reporting platform issues)

`Optional`sandbox

sandbox?: boolean

When true, this response contains simulated data from sandbox mode.

`Optional`ext

ext?: ExtensionObject

Interface GetMediaBuyDeliveryResponse

Index

Properties

Properties

Optionalcontext_id

Optionalcontext

Optionaltask_id

status

Optionalmessage

Optionaltimestamp

Optionalreplayed

Optionaladcp_error

Optionalpush_notification_config

Optionalgovernance_context

Optionalpayload

Optionaladcp_version

Optionaladcp_major_version

Optionalnotification_type

Optionalpartial_data

Optionalunavailable_count

Minimum

Optionalsequence_number

Minimum

Optionalnext_expected_at

Format

reporting_period

Type Declaration

start: string

Format

end: string

Format

Optionalcurrency

Pattern

Optionalattribution_window

Optionalaggregated_totals

Type Declaration

impressions: number

Minimum

spend: number

Minimum

Optionalclicks?: number

Minimum

Optionalcompleted_views?: number

Minimum

Optionalviews?: number

Minimum

Optionalconversions?: number

Minimum

Optionalconversion_value?: number

Minimum

Optionalroas?: number

Minimum

Optionalnew_to_brand_rate?: number

Minimum

Maximum

Optionalcost_per_acquisition?: number

Minimum

Optionalcompletion_rate?: number

Minimum

Maximum

Optionalreach?: number

Minimum

Optionalreach_unit?: ReachUnit

Optionalfrequency?: number

Minimum

media_buy_count: number

Minimum

Optionalmetric_aggregates?: DeliveryMetricAggregate[]

media_buy_deliveries

Type Declaration

media_buy_id: string

status: | "active" | "rejected" | "pending_creatives" | "pending_start" | "paused" | "completed" | "canceled" | "pending" | "failed" | "reporting_delayed"

Optionalexpected_availability?: string

Format

Optionalis_adjusted?: boolean

Optionalis_final?: boolean

Optionalfinalized_at?: string

Format

Optionalpricing_model?: PricingModel

totals: DeliveryMetrics & { effective_rate?: number }

`Optional`context_id

`Optional`context

`Optional`task_id

`Optional`message

`Optional`timestamp

`Optional`replayed

`Optional`adcp_error

`Optional`push_notification_config

`Optional`governance_context

`Optional`payload

`Optional`adcp_version

`Optional`adcp_major_version

`Optional`notification_type

`Optional`partial_data

`Optional`unavailable_count

`Optional`sequence_number

`Optional`next_expected_at

`Optional`currency

`Optional`attribution_window

`Optional`aggregated_totals

`Optional`clicks?: number

`Optional`completed_views?: number

`Optional`views?: number

`Optional`conversions?: number

`Optional`conversion_value?: number

`Optional`roas?: number

`Optional`new_to_brand_rate?: number

`Optional`cost_per_acquisition?: number

`Optional`completion_rate?: number

`Optional`reach?: number

`Optional`reach_unit?: ReachUnit

`Optional`frequency?: number

`Optional`metric_aggregates?: DeliveryMetricAggregate[]

status:
| "active"
| "rejected"
| "pending_creatives"
| "pending_start"
| "paused"
| "completed"
| "canceled"
| "pending"
| "failed"
| "reporting_delayed"

`Optional`expected_availability?: string

`Optional`is_adjusted?: boolean

`Optional`is_final?: boolean

`Optional`finalized_at?: string

`Optional`pricing_model?: PricingModel

`Optional`windows?: {
window_start: string;
window_end: string;
totals: DeliveryMetrics;
by_package?: (DeliveryMetrics & { package_id: string })[];
is_final?: boolean;
measurement_window?: string;
}[]

`Optional`daily_breakdown?: {
date: string;
impressions: number;
spend: number;
conversions?: number;
conversion_value?: number;
roas?: number;
new_to_brand_rate?: number;
}[]

`Optional`errors

`Optional`sandbox

`Optional`ext