{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "/schemas/3.1.0-rc.4/media-buy/get-media-buys-request.json",
  "title": "Get Media Buys Request",
  "description": "Request parameters for retrieving media buy status, creative approval state, and optional delivery snapshots",
  "type": "object",
  "allOf": [
    {
      "$ref": "/schemas/3.1.0-rc.4/core/version-envelope.json"
    }
  ],
  "properties": {
    "account": {
      "$ref": "/schemas/3.1.0-rc.4/core/account-ref.json",
      "description": "Account to retrieve media buys for. When omitted, returns data across all accessible accounts."
    },
    "media_buy_ids": {
      "type": "array",
      "description": "Array of media buy IDs to retrieve. When omitted, returns a paginated set of accessible media buys matching status_filter.",
      "items": {
        "type": "string",
        "x-entity": "media_buy"
      },
      "minItems": 1
    },
    "status_filter": {
      "oneOf": [
        {
          "$ref": "/schemas/3.1.0-rc.4/enums/media-buy-status.json"
        },
        {
          "type": "array",
          "items": {
            "$ref": "/schemas/3.1.0-rc.4/enums/media-buy-status.json"
          },
          "minItems": 1
        }
      ],
      "description": "Filter by status. Can be a single status or array of statuses. Defaults to [\"active\"] when media_buy_ids is omitted. When media_buy_ids is provided, no implicit status filter is applied."
    },
    "include_snapshot": {
      "type": "boolean",
      "description": "When true, include a near-real-time delivery snapshot for each package. Snapshots reflect the latest available entity-level stats from the platform (e.g., updated every ~15 minutes on GAM, ~1 hour on batch-only platforms). The staleness_seconds field on each snapshot indicates data freshness. If a snapshot cannot be returned, package.snapshot_unavailable_reason explains why. Defaults to false.",
      "default": false
    },
    "include_history": {
      "type": "integer",
      "description": "When present, include the last N revision history entries for each media buy (returns min(N, available entries)). Each entry contains revision number, timestamp, actor, and a summary of what changed. Omit or set to 0 to exclude history (default). Recommended: 5-10 for monitoring, 50+ for audit.",
      "minimum": 0,
      "maximum": 1000,
      "default": 0
    },
    "include_webhook_activity": {
      "type": "boolean",
      "description": "When true, each returned media buy includes a `webhook_activity` array describing recent delivery-report webhook fires for the calling principal. Used by buyer agents to verify whether a publisher actually fired against the buyer's registered endpoint and what the endpoint returned — closes the operator-ticket loop for webhook debugging. Scoped to the calling principal: a buyer sees only fires targeting its own endpoint, even when multiple principals share visibility into the same media buy. Defaults to false. See `webhook_activity_limit` for the per-buy cap.",
      "default": false
    },
    "webhook_activity_limit": {
      "type": "integer",
      "description": "Maximum number of webhook delivery records to return per media buy, ordered most-recent first. Ignored when `include_webhook_activity` is false. Sellers that surface webhook activity MUST retain records for at least 30 days from each record's `completed_at` (see `webhook_activity` description in the response schema for the `pending`-status carve-out); sellers unable to honor that floor MUST omit the field entirely rather than truncate. When a buy has more historical fires than the limit, only the most recent are returned — there is no cursor for older fires; this surface is a debug aid, not a full audit log.",
      "minimum": 1,
      "maximum": 200,
      "default": 50
    },
    "pagination": {
      "$ref": "/schemas/3.1.0-rc.4/core/pagination-request.json",
      "description": "Cursor-based pagination controls. Strongly recommended when querying broad scopes (for example, all active media buys in an account)."
    },
    "context": {
      "$ref": "/schemas/3.1.0-rc.4/core/context.json"
    },
    "ext": {
      "$ref": "/schemas/3.1.0-rc.4/core/ext.json"
    }
  },
  "additionalProperties": true
}