meta_ads_search_ad_library

Search Meta Ad Library

Meta

Description

Search the Meta Ad Library for ads from any advertiser. Returns real creative content — ad copy (primary text, headline, description, CTA), landing URLs, run dates, platforms, and media source/mirrored URLs. Served from Hopkin's scraped ad-library corpus, results under \

Read-onlyIdempotentOpen-world

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "meta_ads_search_ad_library",
    "arguments": {
      "search_terms": "running shoes",
      "ad_reached_countries": [
        "US"
      ],
      "reason": "Competitive research on running shoe ads"
    }
  }
}

Parameters

NameTypeRequiredDescription
ad_reached_countries array Required REQUIRED. ISO-3166-1 alpha-2 country codes (e.g. ["US", "GB"] — use "GB" not "UK") or ["ALL"]. Warning: ["ALL"] may return very large result sets — use with small limit values.
reason string Required Why this tool call is neededminLength: 1, maxLength: 500
Optional parameters (14)
NameTypeRequiredDescription
search_terms string Optional Keywords to search for in ad content. Spaces act as AND. Use the language the ad is written in.maxLength: 100
search_type string Optional Search mode: KEYWORD_UNORDERED (default, any order) or KEYWORD_EXACT_PHRASE
KEYWORD_UNORDERED KEYWORD_EXACT_PHRASE
search_page_ids array Optional Filter by up to 10 Facebook Page IDs. Use this for competitor/brand lookups.
ad_type string Optional Filter by ad category. Default: ALL
ALL EMPLOYMENT_ADS FINANCIAL_PRODUCTS_AND_SERVICES_ADS HOUSING_ADS POLITICAL_AND_ISSUE_ADS
ad_active_status string Optional Filter by delivery status. Default: ACTIVE
ACTIVE INACTIVE ALL
ad_delivery_date_min string Optional Minimum delivery date (YYYY-MM-DD)
ad_delivery_date_max string Optional Maximum delivery date (YYYY-MM-DD)
media_type string Optional Filter by media type
ALL IMAGE MEME VIDEO NONE
publisher_platforms array Optional Filter by platform(s)
languages array Optional Filter by language (ISO 639-1 codes)
limit integer Optional Results per page (default: 25, max: 50). Note: 200 calls/hour rate limit — use larger pages to conserve quota.min: 1, max: 50
cursor string Optional Pagination cursor from previous responseminLength: 1
include_raw boolean Optional Also return raw_data, the scraped Meta Ad Library payload behind the normalized fields. Off by default. A carousel or dynamic (dco, dpa) ad's real copy is per card: its normalized headline and primary_text hold only the ad-level copy, often a catalog template such as '{{product.name}}'. Such ads carry `cards`, one per card in order, with its title, body, link_url, cta_text (plus caption and link_description when present) and an image and/or video link: our mirror, or the card's own Meta CDN URL marked short_lived (it expires) when not mirrored yet. include_raw adds only the full scraped payload behind them. Raw rows are large (~9.7 KB per ad on average and up to 268 KB), so pass a small `limit` (e.g. 3-5) when setting this.
connection_id string Optional Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call <platform>_list_connections to discover available connection IDs.

Examples

Search by keyword

{
  "search_terms": "running shoes",
  "ad_reached_countries": [
    "US"
  ],
  "reason": "Competitive research on running shoe ads"
}

hopkin meta search-ad-library --search-terms running shoes --ad-reached-countries US

Search by page ID

{
  "search_page_ids": [
    "123456789"
  ],
  "ad_reached_countries": [
    "US"
  ],
  "reason": "View competitor ads"
}

hopkin meta search-ad-library --search-page-ids 123456789 --ad-reached-countries US

Video ads only

{
  "search_terms": "fitness",
  "ad_reached_countries": [
    "US"
  ],
  "media_type": "VIDEO",
  "reason": "Creative research"
}

hopkin meta search-ad-library --search-terms fitness --ad-reached-countries US --media-type VIDEO