Search Meta Ad Library (`adsap_search_ad_library`)

Platform: Meta · Read or write: Read · Plan: Early Access · Consumes a task: No · Preview supported: No

What it does

Searches Meta’s public Ad Library: the ads any advertiser is running, by brand Page or by keyword, in the countries you name. Each ad comes back with its copy, platforms, languages and start date. It also carries how many days it has been running and how many people it reached in the EU. You can ask for static image ads only, or for video ads only.

When to use it

Use it to see what a competitor is running now. It needs countries and either search_terms or page_ids.
media_type separates static from video. STATIC returns image ads only and VIDEO returns video ads only. Without it the list mixes both, and nothing in it marks which is which.
To study one advertiser, search its name first. The answer lists the Pages it found under pages. Search again with that Page’s ID in page_ids.
search_type set to KEYWORD_EXACT_PHRASE matches the exact phrase. The default matches the words in any order, which returns more unrelated ads.
eu_total_reach and days_running show which ads an advertiser keeps running and pushes. Reach covers the whole EU, not one country. Meta publishes no spend for commercial ads.
publisher_platforms, languages, ad_delivery_date_min and ad_delivery_date_max narrow the list by platform, language and delivery date.
include_targeting adds the age range, gender and locations the advertiser chose.

Worked example

You ask

“Which static ads is the Page 100000000000000 running in France? Biggest reach first.”

The assistant calls `adsap_search_ad_library`


{
  "ad_account_id": "act_1234567890",
  "countries": ["FR"],
  "page_ids": ["100000000000000"],
  "media_type": "STATIC",
  "limit": 25
}

Adsap returns

The field names are the ones Adsap returns. The values are examples.


{
  "ok": true,
  "data": {
    "ads": [
      {
        "id": "1000000000000001",
        "page_id": "100000000000000",
        "page_name": "Example Shoes",
        "ad_creative_bodies": ["Free delivery on orders over 100 euros."],
        "ad_creative_link_titles": ["New season"],
        "ad_creative_link_descriptions": ["Shop the new collection."],
        "ad_creative_link_captions": ["example.com"],
        "library_url": "https://www.facebook.com/ads/library/?id=1000000000000001",
        "ad_creation_time": "2026-09-22T08:00:00+0000",
        "ad_delivery_start_time": "2026-09-23",
        "ad_delivery_stop_time": null,
        "days_running": 13,
        "publisher_platforms": ["facebook", "instagram"],
        "languages": ["fr"],
        "eu_total_reach": 1162470,
        "media_type": "MEME"
      }
    ]
  },
  "meta": {
    "countries": ["FR"],
    "media_type": "STATIC",
    "count": 1,
    "has_next": true,
    "paging_after": "static.eyJpIjoiQVFIUiIsIm0iOiJBUUhSIn0",
    "source": "meta_live"
  }
}

How to read it

Each entry in ads is one ad. eu_total_reach is the number of people it reached across the EU, and days_running counts the days since it started. An ad with a high reach that has run for weeks is one the advertiser keeps paying for. library_url opens the ad on Meta’s Ad Library website.

media_type on an ad names its kind of static ad. Meta sorts still images into IMAGE, a plain picture, and MEME, a picture with text on it. STATIC returns both. When has_next is true, more ads exist: the assistant sends paging_after back as after, with the same filters, to get the next page.

Parameters

Descriptions are shortened from the tool schema. Your assistant sees the full text.

Name	Type	Required	Description
`ad_account_id`	string	Yes	Your ad account ID (act_xxx). Required: Meta only serves Ad Library results to callers with an active ad account; also anchors the workspace ownership check + Meta budget.
`countries`	array of string	Yes	ISO-2 country codes the ads reached, e.g. [“FR”], [“GB”,“DE”]. Required by Meta (ad_reached_countries). For ordinary commercial ads, only EU/UK countries can return results (see the coverage ceiling in the tool description)…
`search_terms`	string	No	Keyword/phrase to match in ad creative text (max 100 characters, Meta’s limit). Provide this and/or page_ids. Matching is broad by default: see search_type, and use data.pages in the result to find the advertiser you meant.
`page_ids`	array of string	No	Facebook Page IDs to restrict the search to (returns only ads run by these pages; max 10, Meta’s limit). Provide this and/or search_terms. No page ID yet?
`ad_type`	one of `ALL`, `POLITICAL_AND_ISSUE_ADS`, `HOUSING_ADS`, `EMPLOYMENT_ADS`, `FINANCIAL_PRODUCTS_AND_SERVICES_ADS`, `CREDIT_ADS`	No	Category of ads. Default ALL (all commercial ads). Use POLITICAL_AND_ISSUE_ADS etc. for the special transparency categories.
`ad_active_status`	one of `ALL`, `ACTIVE`, `INACTIVE`	No	Filter by whether the ad is currently running. Default ACTIVE (what a competitor is running now). Use ALL to include stopped ads.
`media_type`	one of `ALL`, `STATIC`, `IMAGE`, `MEME`, `VIDEO`, `NONE`	No	Filter by the ad’s media. STATIC = every still-image ad (use this whenever the user asks for static / image / non-video ads), VIDEO = video ads only. Default ALL.
`search_type`	one of `KEYWORD_UNORDERED`, `KEYWORD_EXACT_PHRASE`	No	How search_terms is matched. KEYWORD_UNORDERED (default) matches the words in any order, which is broad. KEYWORD_EXACT_PHRASE matches the exact phrase only: use it for a brand or product name to cut unrelated ads.
`publisher_platforms`	array of one of `FACEBOOK`, `INSTAGRAM`, `AUDIENCE_NETWORK`, `MESSENGER`, `WHATSAPP`, `OCULUS`, `THREADS`, `STREAMING_SERVICES`	No	Only ads that ran on these Meta platforms, e.g. [“INSTAGRAM”]. An ad that ran on Instagram AND elsewhere still matches: this means “appeared on”, not “appeared only on”. Default: every platform.
`languages`	array of string	No	Only ads written in these languages, as ISO 639-1 codes, e.g. [“fr”], [“en”,“de”]. Default: every language.
`ad_delivery_date_min`	string	No	Only ads delivered on or after this date (YYYY-MM-DD). Use for ‘ads launched since …’.
`ad_delivery_date_max`	string	No	Only ads delivered on or before this date (YYYY-MM-DD).
`include_targeting`	boolean	No	Also return each ad’s declared targeting (age range, gender, locations). Default false: it makes every row heavier, so ask for it only when the user wants to know WHO an advertiser targets.
`limit`	number	No	Max ads to return per page. Default 25, max 50 (Meta’s cap). Meta can return fewer than asked even when more exist: trust meta.has_next, not the count.
`after`	string	No	Pagination cursor from a previous response’s meta.paging_after, to fetch the next page. Re-send the SAME filters with it (a cursor from a media_type STATIC search only works with media_type STATIC).

Example prompts

“Show me the static ads this brand is running in France.”
“Which of their video ads have run the longest in Germany?”
“Find ads that mention this exact product name in Spain, on Instagram only.”

Notes

Meta’s public data covers commercial ads that reached the EU or the UK. A search on another country returns only the ads that also reached the EU or the UK, which is often none. An empty result there does not mean the advertiser is inactive. - A few ads have both an image version and a video version. Meta returns them under both STATIC and VIDEO. - Meta can return fewer ads than limit while more exist. has_next is the reliable sign. - A search result has no picture. To see the ads, the assistant follows with adsap_get_ad_library_snapshot.

adsap_create_ad_from_ig_post: Turn an existing Instagram post, video, or reel into an ad inside an EXISTING ad set: Meta Ads Manager’s “Use existing post”.
adsap_get_ad_library_snapshot: SHOW what Ad Library ads ACTUALLY LOOK LIKE (creative, copy, page name), in a SELF-CONTAINED card.
adsap_get_ad_preview: Render a pixel-accurate visual preview of an existing Meta ad (real Meta render; video ads also get an animated clip in the interactive…
adsap_get_creative_performance: Ranked creative performance analysis with fatigue detection.
adsap_get_import_status: Check progress of a Meta historical-asset import started with adsap_import_account_creatives: status, phase (images then videos)…
adsap_get_preview_clip: Fetch the animated placement-preview clip (recorded video of the real Meta preview) for an ad+placement previously rendered with…
adsap_get_upload_status: Check status of an async video upload.
adsap_import_account_creatives: Import ALL historical creative assets (images + videos) that already exist in a Meta ad account into the Adsap Creative Library.
adsap_list_creative_assets: List uploaded Meta creative images and videos in the ad account asset library.
adsap_list_drive_files: Browse Google Drive for creative image/video files to upload to Meta.
adsap_list_dropbox_files: Browse Dropbox for creative image/video files to upload to Meta.
adsap_list_ig_media: List an Instagram account’s recent media/posts (live from Meta): the posts, reels, and stories that can be promoted.
adsap_replace_ad_creative: DESTRUCTIVE.
adsap_upload_creative: Upload image/video from Google Drive or Dropbox to a Meta ad account.

Guide

Read Creatives for the workflow around this tool, and the Tool reference for every tool.

Search Meta Ad Library (adsap_search_ad_library)