Interface GetMediaBuyDeliveryResponse

Response payload for get_media_buy_delivery task

interface GetMediaBuyDeliveryResponse {
    notification_type?: "scheduled" | "final" | "delayed" | "adjusted";
    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;
    };
    media_buy_deliveries: {
        media_buy_id: string;
        status: | "active"
        | "rejected"
        | "pending_activation"
        | "paused"
        | "completed"
        | "canceled"
        | "failed"
        | "pending"
        | "reporting_delayed";
        expected_availability?: string;
        is_adjusted?: boolean;
        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;
                by_catalog_item?: (
                    DeliveryMetrics & {
                        content_id?: string;
                        content_id_type?: ContentIDType;
                    }
                )[];
                by_creative?: (
                    DeliveryMetrics & { creative_id: string; weight?: number }
                )[];
                by_keyword?: (
                    DeliveryMetrics & {
                        keyword?: string;
                        match_type?: "broad"
                        | "phrase"
                        | "exact";
                    }
                )[];
                by_geo?: (
                    DeliveryMetrics & {
                        geo_level?: GeographicTargetingLevel;
                        system?: string;
                        geo_code?: string;
                        geo_name?: string;
                    }
                )[];
                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 }
                )[];
                by_placement_truncated?: boolean;
                daily_breakdown?: {
                    date: string;
                    impressions: number;
                    spend: number;
                    conversions?: number;
                    conversion_value?: number;
                    roas?: number;
                    new_to_brand_rate?: number;
                }[];
            }
        )[];
        daily_breakdown?: {
            date: string;
            impressions: number;
            spend: number;
            conversions?: number;
            conversion_value?: number;
            roas?: number;
            new_to_brand_rate?: number;
        }[];
    }[];
    errors?: Error[];
    sandbox?: boolean;
    context?: ContextObject;
    ext?: ExtensionObject;
}

Index

Properties

notification_type? partial_data? unavailable_count? sequence_number? next_expected_at? reporting_period currency? attribution_window? aggregated_totals? media_buy_deliveries errors? sandbox? context? ext?

Properties

`Optional`notification_type

notification_type?: "scheduled" | "final" | "delayed" | "adjusted"

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 updated data

`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)

`Optional`sequence_number

sequence_number?: number

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

`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')

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)
end: string
ISO 8601 end timestamp in UTC (e.g., 2024-02-05T23:59:59Z)

`Optional`currency

currency?: string

ISO 4217 currency code

`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;
}

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
spend: number
Total amount spent across all media buys
Optionalclicks?: number
Total clicks across all media buys (if applicable)
Optionalcompleted_views?: number
Total audio/video completions across all media buys (if applicable)
Optionalviews?: number
Total views across all media buys (if applicable)
Optionalconversions?: number
Total conversions across all media buys (if applicable)
Optionalconversion_value?: number
Total conversion value across all media buys (if applicable)
Optionalroas?: number
Aggregate return on ad spend across all media buys (total conversion_value / total spend)
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)
Optionalcost_per_acquisition?: number
Aggregate cost per conversion across all media buys (total spend / total conversions)
Optionalcompletion_rate?: number
Aggregate completion rate across all media buys (weighted by impressions, not a simple average of per-buy rates)
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.
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.
media_buy_count: number
Number of media buys included in the response

media_buy_deliveries

media_buy_deliveries: {
    media_buy_id: string;
    status:
        | "active"
        | "rejected"
        | "pending_activation"
        | "paused"
        | "completed"
        | "canceled"
        | "failed"
        | "pending"
        | "reporting_delayed";
    expected_availability?: string;
    is_adjusted?: boolean;
    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;
            by_catalog_item?: (
                DeliveryMetrics & {
                    content_id?: string;
                    content_id_type?: ContentIDType;
                }
            )[];
            by_creative?: (
                DeliveryMetrics & { creative_id: string; weight?: number }
            )[];
            by_keyword?: (
                DeliveryMetrics & {
                    keyword?: string;
                    match_type?: "broad"
                    | "phrase"
                    | "exact";
                }
            )[];
            by_geo?: (
                DeliveryMetrics & {
                    geo_level?: GeographicTargetingLevel;
                    system?: string;
                    geo_code?: string;
                    geo_name?: string;
                }
            )[];
            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 }
            )[];
            by_placement_truncated?: boolean;
            daily_breakdown?: {
                date: string;
                impressions: number;
                spend: number;
                conversions?: number;
                conversion_value?: number;
                roas?: number;
                new_to_brand_rate?: number;
            }[];
        }
    )[];
    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_activation"
    | "paused"
    | "completed"
    | "canceled"
    | "failed"
    | "pending"
    | "reporting_delayed"
Current media buy status. Lifecycle states use the same taxonomy as media-buy-status (pending_activation, active, paused, completed, rejected, canceled). In webhook context, reporting_delayed indicates data temporarily unavailable. pending is accepted as a legacy alias for pending_activation.
Optionalexpected_availability?: string
When delayed data is expected to be available (only present when status is reporting_delayed)
Optionalis_adjusted?: boolean
Indicates this delivery contains updated data for a previously reported period. Buyer should replace previous period data with these totals.
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;
        by_catalog_item?: (
            DeliveryMetrics & {
                content_id?: string;
                content_id_type?: ContentIDType;
            }
        )[];
        by_creative?: (DeliveryMetrics & { creative_id: string; weight?: number })[];
        by_keyword?: (
            DeliveryMetrics & {
                keyword?: string;
                match_type?: "broad"
                | "phrase"
                | "exact";
            }
        )[];
        by_geo?: (
            DeliveryMetrics & {
                geo_level?: GeographicTargetingLevel;
                system?: string;
                geo_code?: string;
                geo_name?: string;
            }
        )[];
        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 }
        )[];
        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
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`context

context?: ContextObject

`Optional`ext

ext?: ExtensionObject

Interface GetMediaBuyDeliveryResponse

Index

Properties

Properties

Optionalnotification_type

Optionalpartial_data

Optionalunavailable_count

Optionalsequence_number

Optionalnext_expected_at

reporting_period

Type Declaration

start: string

end: string

Optionalcurrency

Optionalattribution_window

Optionalaggregated_totals

Type Declaration

impressions: number

spend: number

Optionalclicks?: number

Optionalcompleted_views?: number

Optionalviews?: number

Optionalconversions?: number

Optionalconversion_value?: number

Optionalroas?: number

Optionalnew_to_brand_rate?: number

Optionalcost_per_acquisition?: number

Optionalcompletion_rate?: number

Optionalreach?: number

Optionalreach_unit?: ReachUnit

Optionalfrequency?: number

media_buy_count: number

media_buy_deliveries

Type Declaration

media_buy_id: string

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

Optionalexpected_availability?: string

Optionalis_adjusted?: boolean

Optionalpricing_model?: PricingModel

totals: DeliveryMetrics & { effective_rate?: number }

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

Optionalerrors

Optionalsandbox

Optionalcontext

Optionalext

Settings

On This Page

`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

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

`Optional`expected_availability?: string

`Optional`is_adjusted?: boolean

`Optional`pricing_model?: PricingModel

`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`context

`Optional`ext