search

Admitted input schema

{
  "type": "object",
  "properties": {
    "active_status": {
      "type": "string",
      "minLength": 0,
      "maxLength": 4096,
      "enum": [
        "all",
        "active",
        "inactive"
      ],
      "description": "Filter by whether the ad is still running."
    },
    "ad_type": {
      "type": "string",
      "minLength": 0,
      "maxLength": 4096,
      "enum": [
        "all",
        "political_and_issue_ads",
        "housing_ads",
        "employment_ads",
        "credit_ads",
        "financial_products_and_services_ads"
      ],
      "description": "Ad category filter. political_and_issue_ads MAY add spend + impressions ranges when Meta discloses them (often absent)."
    },
    "country": {
      "type": "string",
      "minLength": 0,
      "maxLength": 4096,
      "description": "Two-letter ISO country (US, GB, DE, BR…) the ads target, or ALL for a bounded multi-region sweep (slower). Default US."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 60,
      "description": "Max ads to return (1-60)."
    },
    "media_type": {
      "type": "string",
      "minLength": 0,
      "maxLength": 4096,
      "enum": [
        "all",
        "image",
        "video",
        "meme",
        "image_and_meme",
        "none"
      ],
      "description": "Creative format filter."
    },
    "period": {
      "type": "string",
      "minLength": 0,
      "maxLength": 4096,
      "enum": [
        "",
        "last24h",
        "last7d",
        "last14d",
        "last30d"
      ],
      "description": "Limit to ads active in this window. Blank = all time."
    },
    "platforms": {
      "type": "string",
      "minLength": 0,
      "maxLength": 4096,
      "description": "Comma-separated publisher filter: FACEBOOK,INSTAGRAM,MESSENGER,AUDIENCE_NETWORK,THREADS,WHATSAPP. Blank = all."
    },
    "q": {
      "type": "string",
      "minLength": 0,
      "maxLength": 4096,
      "description": "Keyword/phrase to search ads for (e.g. \"running shoes\", \"crypto wallet\"). Defaults to a demo query if omitted."
    },
    "resolve_advertiser": {
      "type": "boolean",
      "description": "Also resolve each advertiser’s page identity (verified status, categories, profile pic). Slower. Default false."
    },
    "sort_by": {
      "type": "string",
      "minLength": 0,
      "maxLength": 4096,
      "enum": [
        "impressions_desc",
        "most_recent"
      ],
      "description": "most_recent (newest/currently-running first — default) or impressions_desc (all-time highest-impression ads, often older/ended)."
    }
  },
  "required": [
    "q"
  ],
  "additionalProperties": false
}