{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/media-buy/get-media-buy-delivery-request.json",
  "title": "Get Media Buy Delivery Request",
  "description": "Request parameters for retrieving comprehensive delivery metrics",
  "x-tool-summary": "Retrieve media-buy delivery metrics with optional date, package, window, attribution, and dimension breakdowns.",
  "type": "object",
  "allOf": [
    {
      "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/core/version-envelope.json"
    }
  ],
  "properties": {
    "account": {
      "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/core/account-ref.json",
      "description": "Filter delivery data to a specific account. When omitted, returns data across all accessible accounts."
    },
    "media_buy_ids": {
      "type": "array",
      "description": "Array of media buy IDs to get delivery data for",
      "items": {
        "type": "string",
        "x-entity": "media_buy"
      },
      "minItems": 1
    },
    "status_filter": {
      "oneOf": [
        {
          "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/media-buy-status.json"
        },
        {
          "type": "array",
          "items": {
            "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/media-buy-status.json"
          },
          "minItems": 1
        }
      ],
      "description": "Filter by status. Can be a single status or array of statuses"
    },
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Inclusive start date for the reporting period (YYYY-MM-DD). When omitted along with end_date, returns campaign lifetime data. Only accepted when the product's reporting_capabilities.date_range_support is 'date_range'."
    },
    "end_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Exclusive end date for the reporting period (YYYY-MM-DD). Must be later than start_date. When omitted along with start_date, returns campaign lifetime data. Only accepted when the product's reporting_capabilities.date_range_support is 'date_range'."
    },
    "include_package_daily_breakdown": {
      "type": "boolean",
      "default": false,
      "description": "When true, include daily_breakdown arrays within each package in by_package. Useful for per-package pacing analysis and line-item monitoring. Omit or set false to reduce response size — package daily data can be large for multi-package buys over long flights."
    },
    "requested_metrics": {
      "type": "array",
      "description": "Optional list of metrics to include in the response. When omitted, all available metrics are included (unchanged behavior). Applies to every metrics-bearing object in the response: totals, by_package, daily and window slices, and breakdown rows. impressions and spend are always included regardless of this list. Requesting a leaf metric identity returns its canonical nested carrier — e.g. requesting viewable_rate returns the viewability object, requesting quartile_75 returns quartile_data — never a flat duplicate. Metrics requested but not available for this buy are omitted from the response without error; contract accountability is unchanged — missing_metrics still reconciles against committed_metrics, but sellers MUST NOT list a metric in missing_metrics when its absence is solely due to this narrowing. Must be a subset of the product's reporting_capabilities.available_metrics; values outside the declared set are ignored. Subset evaluation follows the container-subsumption rule in enums/available-metric.json. Sort is evaluated before narrowing: excluding a metric from this list never triggers the sort_by fallback, and breakdown rows may be ordered by a metric absent from the narrowed payload — the applied-sort echo still names it. Same narrowing semantics as reporting_webhook.requested_metrics, with one shape difference: this field requires at least one entry when present (omit it entirely for full payloads), while the webhook field permits an empty array with the same meaning as omission.",
      "items": {
        "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/available-metric.json"
      },
      "uniqueItems": true,
      "minItems": 1
    },
    "time_granularity": {
      "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/reporting-frequency.json",
      "description": "Per-window slice granularity for the pull, using the same vocabulary as reporting_webhook.reporting_frequency. When set, the seller returns per-window delivery slices over the date range — useful for reconstructing data a buyer's webhook receiver missed, since the slice payload is shape-aligned with what reporting_webhook would have delivered for the same window. Capability-scoped: the value MUST be one of the seller's declared reporting_capabilities.windowed_pull_granularities; otherwise the seller MUST return UNSUPPORTED_GRANULARITY. When omitted, behavior is unchanged (cumulative aggregates plus optional daily breakdowns per existing fields)."
    },
    "include_window_breakdown": {
      "type": "boolean",
      "default": false,
      "description": "When true, the response includes media_buy_deliveries[].windows[] — an array of per-window delivery slices over the date range at the requested time_granularity. Ignored when time_granularity is omitted. Each window's payload mirrors what reporting_webhook would have delivered for the same window, enabling lossless GET-path recovery for buyers who missed webhook fires. Omit or set false to reduce response size when only cumulative aggregates are needed."
    },
    "attribution_window": {
      "type": "object",
      "description": "Attribution window to apply for conversion metrics. When provided, the seller returns conversion data using the requested lookback windows instead of their platform default. The seller echoes the applied window in the response. Sellers that do not support configurable windows ignore this field and return their default. Check get_adcp_capabilities conversion_tracking.attribution_windows for available options.",
      "properties": {
        "post_click": {
          "allOf": [
            {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/core/duration.json"
            }
          ],
          "description": "Post-click attribution window to apply."
        },
        "post_view": {
          "allOf": [
            {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/core/duration.json"
            }
          ],
          "description": "Post-view attribution window to apply."
        },
        "model": {
          "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/attribution-model.json",
          "description": "Attribution model to use. When omitted, the seller applies their default model."
        }
      },
      "additionalProperties": true
    },
    "reporting_dimensions": {
      "type": "object",
      "description": "Request dimensional breakdowns in delivery reporting. Each key enables a specific breakdown dimension within by_package — include as an empty object (e.g., \"device_type\": {}) to activate with defaults. Omit entirely for no breakdowns (backward compatible). Unsupported dimensions are silently omitted from the response. Note: keyword, catalog_item, and creative breakdowns are returned automatically when the seller supports them; including their keys here is optional and upgrades them to a negotiated contract (limit, sort, and truncation disclosure) without changing the automatic default.",
      "properties": {
        "catalog_item": {
          "type": "object",
          "description": "Request a negotiated catalog_item breakdown. Omitting this key preserves the automatic behavior — sellers return catalog_item rows at their discretion with no truncation contract. Including it (even as {}) makes the truncation disclosure and applied-sort echo binding.",
          "properties": {
            "limit": {
              "type": "integer",
              "minimum": 1,
              "description": "Maximum number of catalog_item entries to return. When omitted, the seller returns its automatic default set."
            },
            "sort_by": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/sort-metric.json",
              "description": "Metric to sort breakdown rows by, in `sort_direction` order (descending by default). Falls back to 'spend' when the seller does not report the requested metric at this breakdown's row grain; on fallback the sort direction resets to 'desc'. Rows lacking a value for the applied sort metric order last regardless of direction. The applied sort is echoed in the response.",
              "default": "spend"
            },
            "sort_direction": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/sort-direction.json",
              "description": "Direction for sort_by ordering. Defaults to 'desc' (largest first). 'asc' enables bottom-N queries (e.g., the 25 worst placements by viewable_rate) that cannot be recovered from a truncated descending pull. Sellers MUST apply the requested direction to the applied sort metric — direction has no availability fallback.",
              "default": "desc"
            }
          },
          "additionalProperties": true
        },
        "creative": {
          "type": "object",
          "description": "Request a negotiated creative breakdown. Omitting this key preserves the automatic behavior — sellers return creative rows at their discretion with no truncation contract. Including it (even as {}) makes the truncation disclosure and applied-sort echo binding.",
          "properties": {
            "limit": {
              "type": "integer",
              "minimum": 1,
              "description": "Maximum number of creative entries to return. When omitted, the seller returns its automatic default set."
            },
            "sort_by": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/sort-metric.json",
              "description": "Metric to sort breakdown rows by, in `sort_direction` order (descending by default). Falls back to 'spend' when the seller does not report the requested metric at this breakdown's row grain; on fallback the sort direction resets to 'desc'. Rows lacking a value for the applied sort metric order last regardless of direction. The applied sort is echoed in the response.",
              "default": "spend"
            },
            "sort_direction": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/sort-direction.json",
              "description": "Direction for sort_by ordering. Defaults to 'desc' (largest first). 'asc' enables bottom-N queries (e.g., the 25 worst placements by viewable_rate) that cannot be recovered from a truncated descending pull. Sellers MUST apply the requested direction to the applied sort metric — direction has no availability fallback.",
              "default": "desc"
            }
          },
          "additionalProperties": true
        },
        "keyword": {
          "type": "object",
          "description": "Request a negotiated keyword breakdown. Omitting this key preserves the automatic behavior — sellers return keyword rows at their discretion with no truncation contract. Including it (even as {}) makes the truncation disclosure and applied-sort echo binding.",
          "properties": {
            "limit": {
              "type": "integer",
              "minimum": 1,
              "description": "Maximum number of keyword entries to return. When omitted, the seller returns its automatic default set."
            },
            "sort_by": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/sort-metric.json",
              "description": "Metric to sort breakdown rows by, in `sort_direction` order (descending by default). Falls back to 'spend' when the seller does not report the requested metric at this breakdown's row grain; on fallback the sort direction resets to 'desc'. Rows lacking a value for the applied sort metric order last regardless of direction. The applied sort is echoed in the response.",
              "default": "spend"
            },
            "sort_direction": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/sort-direction.json",
              "description": "Direction for sort_by ordering. Defaults to 'desc' (largest first). 'asc' enables bottom-N queries (e.g., the 25 worst placements by viewable_rate) that cannot be recovered from a truncated descending pull. Sellers MUST apply the requested direction to the applied sort metric — direction has no availability fallback.",
              "default": "desc"
            }
          },
          "additionalProperties": true
        },
        "geo": {
          "type": "object",
          "description": "Request geographic breakdown. Check reporting_capabilities.supports_geo_breakdown for available levels and systems.",
          "properties": {
            "geo_level": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/geo-level.json",
              "description": "Geographic granularity level for the breakdown"
            },
            "system": {
              "anyOf": [
                {
                  "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/metro-system.json"
                },
                {
                  "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/postal-system.json"
                },
                {
                  "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/legacy-postal-system.json"
                }
              ],
              "description": "Optional classification system for metro or postal_area levels. Metro uses metro-system values (e.g., 'nielsen_dma'); native postal_area uses country-local postal-system values with country (e.g., country 'US', system 'zip'); deprecated legacy postal_area requests may use legacy-postal-system values such as 'us_zip'. Omit to request the level without selecting a specific system."
            },
            "country": {
              "type": "string",
              "pattern": "^[A-Z]{2}$",
              "description": "ISO 3166-1 alpha-2 country code. Required for native postal_area requests; omitted for legacy postal_area and non-postal geo requests."
            },
            "limit": {
              "type": "integer",
              "minimum": 1,
              "default": 25,
              "description": "Maximum number of geo entries to return. Defaults to 25. When truncated, by_geo_truncated is true in the response."
            },
            "sort_by": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/sort-metric.json",
              "description": "Metric to sort breakdown rows by, in `sort_direction` order (descending by default). Falls back to 'spend' when the seller does not report the requested metric at this breakdown's row grain; on fallback the sort direction resets to 'desc'. Rows lacking a value for the applied sort metric order last regardless of direction. The applied sort is echoed in the response.",
              "default": "spend"
            },
            "sort_direction": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/sort-direction.json",
              "description": "Direction for sort_by ordering. Defaults to 'desc' (largest first). 'asc' enables bottom-N queries (e.g., the 25 worst placements by viewable_rate) that cannot be recovered from a truncated descending pull. Sellers MUST apply the requested direction to the applied sort metric — direction has no availability fallback.",
              "default": "desc"
            }
          },
          "required": [
            "geo_level"
          ],
          "allOf": [
            {
              "if": {
                "properties": {
                  "geo_level": {
                    "enum": [
                      "country",
                      "region"
                    ]
                  }
                },
                "required": [
                  "geo_level"
                ]
              },
              "then": {
                "not": {
                  "anyOf": [
                    {
                      "required": [
                        "country"
                      ]
                    },
                    {
                      "required": [
                        "system"
                      ]
                    }
                  ]
                }
              }
            },
            {
              "if": {
                "properties": {
                  "geo_level": {
                    "const": "metro"
                  }
                },
                "required": [
                  "geo_level"
                ]
              },
              "then": {
                "anyOf": [
                  {
                    "not": {
                      "required": [
                        "system"
                      ]
                    }
                  },
                  {
                    "properties": {
                      "system": {
                        "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/metro-system.json"
                      }
                    },
                    "required": [
                      "system"
                    ]
                  }
                ],
                "not": {
                  "required": [
                    "country"
                  ]
                }
              }
            },
            {
              "if": {
                "properties": {
                  "geo_level": {
                    "const": "postal_area"
                  }
                },
                "required": [
                  "geo_level"
                ]
              },
              "then": {
                "anyOf": [
                  {
                    "not": {
                      "anyOf": [
                        {
                          "required": [
                            "country"
                          ]
                        },
                        {
                          "required": [
                            "system"
                          ]
                        }
                      ]
                    }
                  },
                  {
                    "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/core/postal-country-system.json"
                  },
                  {
                    "properties": {
                      "system": {
                        "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/legacy-postal-system.json"
                      }
                    },
                    "required": [
                      "system"
                    ],
                    "not": {
                      "required": [
                        "country"
                      ]
                    }
                  }
                ]
              }
            }
          ],
          "additionalProperties": true
        },
        "device_type": {
          "type": "object",
          "description": "Request device type breakdown.",
          "properties": {
            "limit": {
              "type": "integer",
              "minimum": 1,
              "description": "Maximum number of entries to return. When omitted, all entries are returned (the enum is small and bounded)."
            },
            "sort_by": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/sort-metric.json",
              "description": "Metric to sort breakdown rows by, in `sort_direction` order (descending by default). Falls back to 'spend' when the seller does not report the requested metric at this breakdown's row grain; on fallback the sort direction resets to 'desc'. Rows lacking a value for the applied sort metric order last regardless of direction. The applied sort is echoed in the response.",
              "default": "spend"
            },
            "sort_direction": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/sort-direction.json",
              "description": "Direction for sort_by ordering. Defaults to 'desc' (largest first). 'asc' enables bottom-N queries (e.g., the 25 worst placements by viewable_rate) that cannot be recovered from a truncated descending pull. Sellers MUST apply the requested direction to the applied sort metric — direction has no availability fallback.",
              "default": "desc"
            }
          },
          "additionalProperties": true
        },
        "device_platform": {
          "type": "object",
          "description": "Request device platform breakdown.",
          "properties": {
            "limit": {
              "type": "integer",
              "minimum": 1,
              "description": "Maximum number of entries to return. When omitted, all entries are returned (the enum is small and bounded)."
            },
            "sort_by": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/sort-metric.json",
              "description": "Metric to sort breakdown rows by, in `sort_direction` order (descending by default). Falls back to 'spend' when the seller does not report the requested metric at this breakdown's row grain; on fallback the sort direction resets to 'desc'. Rows lacking a value for the applied sort metric order last regardless of direction. The applied sort is echoed in the response.",
              "default": "spend"
            },
            "sort_direction": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/sort-direction.json",
              "description": "Direction for sort_by ordering. Defaults to 'desc' (largest first). 'asc' enables bottom-N queries (e.g., the 25 worst placements by viewable_rate) that cannot be recovered from a truncated descending pull. Sellers MUST apply the requested direction to the applied sort metric — direction has no availability fallback.",
              "default": "desc"
            }
          },
          "additionalProperties": true
        },
        "format": {
          "type": "object",
          "description": "Request delivery broken down by canonical creative format kind. This dimension is negotiated on the GET path. Reporting webhook configuration does not negotiate or guarantee dimensional breakdowns, although a webhook payload may carry the same fields as an extension.",
          "properties": {
            "limit": {
              "type": "integer",
              "minimum": 1,
              "description": "Maximum number of format rows to return. When omitted, all rows are returned because the canonical format-kind vocabulary is small and bounded."
            },
            "sort_by": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/sort-metric.json",
              "description": "Metric to sort breakdown rows by, in `sort_direction` order (descending by default). Falls back to 'spend' when the seller does not report the requested metric at this breakdown's row grain; on fallback the sort direction resets to 'desc'. Rows lacking a value for the applied sort metric order last regardless of direction. The applied sort is echoed in the response.",
              "default": "spend"
            },
            "sort_direction": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/sort-direction.json",
              "description": "Direction for sort_by ordering. Defaults to 'desc' (largest first). 'asc' enables bottom-N queries (e.g., the 25 worst placements by viewable_rate) that cannot be recovered from a truncated descending pull. Sellers MUST apply the requested direction to the applied sort metric — direction has no availability fallback.",
              "default": "desc"
            }
          },
          "additionalProperties": true
        },
        "audience": {
          "type": "object",
          "description": "Request audience segment breakdown.",
          "properties": {
            "limit": {
              "type": "integer",
              "minimum": 1,
              "default": 25,
              "description": "Maximum number of entries to return. Defaults to 25."
            },
            "sort_by": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/sort-metric.json",
              "description": "Metric to sort breakdown rows by, in `sort_direction` order (descending by default). Falls back to 'spend' when the seller does not report the requested metric at this breakdown's row grain; on fallback the sort direction resets to 'desc'. Rows lacking a value for the applied sort metric order last regardless of direction. The applied sort is echoed in the response.",
              "default": "spend"
            },
            "sort_direction": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/sort-direction.json",
              "description": "Direction for sort_by ordering. Defaults to 'desc' (largest first). 'asc' enables bottom-N queries (e.g., the 25 worst placements by viewable_rate) that cannot be recovered from a truncated descending pull. Sellers MUST apply the requested direction to the applied sort metric — direction has no availability fallback.",
              "default": "desc"
            }
          },
          "additionalProperties": true
        },
        "demographic": {
          "type": "object",
          "description": "Request delivery broken down by demographic. Check the product's reporting_capabilities.supports_demographic_breakdown independently from demographic_targeting. When age_ranges is present, every requested range MUST be exactly supported by exact_predicates or equal one of the declared enumerated_intervals; sellers MUST reject unsupported ranges with UNSUPPORTED_FEATURE rather than silently widen or narrow them.",
          "properties": {
            "age_ranges": {
              "type": "array",
              "description": "Optional canonical age ranges to return as distinct rows. Copying an applied targeting predicate here requests aligned reporting only when the reporting capability supports that exact predicate. Omit to request the product's declared native demographic breakdown.",
              "items": {
                "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/core/demographic-age-range.json"
              },
              "minItems": 1,
              "uniqueItems": true
            },
            "limit": {
              "type": "integer",
              "minimum": 1,
              "default": 25,
              "description": "Maximum number of demographic entries to return. Defaults to 25."
            },
            "sort_by": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/sort-metric.json",
              "description": "Metric to sort breakdown rows by, in `sort_direction` order (descending by default). Falls back to 'spend' when the seller does not report the requested metric at this breakdown's row grain; on fallback the sort direction resets to 'desc'. Rows lacking a value for the applied sort metric order last regardless of direction. The applied sort is echoed in the response.",
              "default": "spend"
            },
            "sort_direction": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/sort-direction.json",
              "description": "Direction for sort_by ordering. Defaults to 'desc' (largest first). 'asc' enables bottom-N queries (e.g., the 25 worst placements by viewable_rate) that cannot be recovered from a truncated descending pull. Sellers MUST apply the requested direction to the applied sort metric — direction has no availability fallback.",
              "default": "desc"
            }
          },
          "additionalProperties": false
        },
        "spot": {
          "type": "object",
          "description": "Request a spot-level as-run airing log for broadcast TV, radio, or other scheduled inventory. Rows are ordered by aired_at ascending. When limit is omitted, sellers SHOULD return the complete log for the requested reporting period.",
          "properties": {
            "limit": {
              "type": "integer",
              "minimum": 1,
              "description": "Optional maximum number of spot rows to return. When the response is incomplete because of this limit or a seller-imposed maximum, by_spot_truncated is true."
            }
          },
          "additionalProperties": true
        },
        "placement": {
          "type": "object",
          "description": "Request placement breakdown.",
          "properties": {
            "limit": {
              "type": "integer",
              "minimum": 1,
              "default": 25,
              "description": "Maximum number of entries to return. Defaults to 25."
            },
            "sort_by": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/sort-metric.json",
              "description": "Metric to sort breakdown rows by, in `sort_direction` order (descending by default). Falls back to 'spend' when the seller does not report the requested metric at this breakdown's row grain; on fallback the sort direction resets to 'desc'. Rows lacking a value for the applied sort metric order last regardless of direction. The applied sort is echoed in the response.",
              "default": "spend"
            },
            "sort_direction": {
              "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/enums/sort-direction.json",
              "description": "Direction for sort_by ordering. Defaults to 'desc' (largest first). 'asc' enables bottom-N queries (e.g., the 25 worst placements by viewable_rate) that cannot be recovered from a truncated descending pull. Sellers MUST apply the requested direction to the applied sort metric — direction has no availability fallback.",
              "default": "desc"
            }
          },
          "additionalProperties": true
        }
      },
      "additionalProperties": true
    },
    "context": {
      "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/core/context.json"
    },
    "ext": {
      "$ref": "https://adcontextprotocol.org/schemas/3.2.0-beta.7/core/ext.json"
    }
  },
  "additionalProperties": true
}