meta-ads-library

Meta Ads Library

Guide for searching the Meta Ads Library and producing structured competitor ad intelligence.

The skill's job is to turn raw scraped ads into useful summaries: top advertisers, common CTAs, recurring hooks, recently launched creatives, and (optionally) enriched lead lists. All output is presented inline in chat — there is no database or persistence layer.

Out of scope — defer to other skills

Request	Send them to
Multi-source competitor research (site, social, search rank, etc., not just ads)	competitor-intel
Generating new ad creative based on what you found	ad-creative-generation

Requirements

• Hyper MCP installed and connected. https://app.hyperfx.ai/mcp
• Apify integration connected at https://app.hyperfx.ai/apps — the Meta Ads Library tools run via Apify under the hood.

If search("meta_ad_library_ads_search") does not find meta_ad_library_ads_search, stop and tell the user to enable Hyper MCP and connect Apify.

How to run the tools in this skill

Every tool in this skill is named by its canonical tool name. Run it with the call your surface gives you:

Surface	Find a tool	Run it
MCP client (Claude, Cursor, Codex, ChatGPT)	search("<what you want to do>"), then describe("<name>")	call("<name>", {...})
Hyper CLI	hyperai search "<what you want to do>", then hyperai describe <name>	hyperai call <name> --json '{...}'

If a tool is not found, its integration is not connected or not enabled for the workspace: stop and tell the user which integration to connect.

Tool surface

Tool	Purpose
meta_ad_library_ads_search	Search the Meta Ads Library by keyword. Returns compact results (title, body, CTA, link, page name, dates, platforms). Max 40 per call.
meta_ad_library_ads_get	Get full details for a specific ad. Requires both ad_archive_id and page_id — both come from meta_ad_library_ads_search results.
meta_ad_library_ads_search_enriched	Search + enrich each result with page contact info (email, phone, website). Slower (multiple API calls per result). Max 20 per call.
meta_ad_library_pages_search	Search Facebook pages by category + location (not by keyword). Useful for building a lead list from a vertical.
meta_ad_library_pages_scrape	Scrape detailed data from specific Facebook page URLs.

Critical rules

1. Public-only data. The Meta Ads Library is public. Don't attempt to bypass any access control or scrape private content.
2. Count limits differ between tools. meta_ad_library_ads_search allows count up to 40. meta_ad_library_ads_search_enriched caps at 20 — exceeding this returns an error.
3. meta_ad_library_ads_get needs two IDs. Both ad_archive_id and page_id are required. Both are returned in every meta_ad_library_ads_search result row — pass them through together.
4. Enriched search is slow. It makes a Facebook page scrape per ad and optionally a website scrape. Only use it when contact info matters (lead-gen workflows). For pure ad intelligence, use the regular meta_ad_library_ads_search.
5. Apify-backed tools fail intermittently. Expect occasional "fetch failed" responses. Retry once after a short delay before reporting the source as missing.
6. Don't over-interpret a single ad. "Brand X is running a discount" is noise. "5 of the top 10 advertisers in this query are running discounts" is signal. Always aggregate before drawing conclusions.

Workflow

Phase 1 — Define the query

Before running anything, agree on:

1. The search query — keyword(s) competitors would target. Examples: "meal kit delivery", "AI marketing tools", "skincare for sensitive skin".
2. Country — ISO code (e.g. "US", "GB", "AU"). Default to "ALL" only if the user explicitly wants global.
3. Active vs all — active_status="active" is usually what you want. Inactive ads are historical and noisier.
4. Time window — period accepts "last24h", "last7d", "last14d", "last30d", or "all_time". Match the window to the user's intent (weekly digest → "last7d", trend research → "last30d").
5. The job — what is this for?
   • Creative trend report → use meta_ad_library_ads_search, summarize patterns across hooks, CTAs, formats.
   • Top advertiser snapshot → use meta_ad_library_ads_search, group by page_name.
   • Lead list → use meta_ad_library_ads_search_enriched, filter for rows with contact_email or contact_website.

Phase 2 — Pull the ads

meta_ad_library_ads_search(
    query="meal kit delivery",
    country="US",
    active_status="active",
    count=40,                # max for this tool
    period="last30d"
)

Each result row includes: ad_archive_id, page_id, page_name, is_active, start_date_formatted, end_date_formatted, title, body, cta_text, link_url, caption, ad_library_url, page_categories, publisher_platform.

For more than 40 ads, paginate by re-calling with offset=40, offset=80, etc.

For lead-gen with contact info:

meta_ad_library_ads_search_enriched(
    query="meal kit delivery",
    country="US",
    active_status="active",
    count=20,                # max for the enriched tool
    scrape_websites=True,
    filter_spam=False
)

Enriched rows add: contact_email, contact_phone, contact_website, page_followers, page_rating, address, business hours.

Phase 3 — Get full creative for the most interesting ads (optional)

meta_ad_library_ads_search returns truncated bodies for some ads. To get the complete creative — including video URLs and images — call meta_ad_library_ads_get on the specific ads worth a deeper look:

meta_ad_library_ads_get(
    ad_archive_id="559220927273823",      # from search results
    page_id="328127803978438"             # from search results
)

Both args come from the same row in meta_ad_library_ads_search. Do this for the top 3–5 ads, not all 40 — each detail call is a separate Apify run.

Phase 4 — Surface the intelligence

Present the findings inline in chat. Pick the format that matches the user's job from Phase 1.

Top advertisers (group by page):

Page	Active ads	Categories	Notable angle
Brand A	12	Restaurant, Meal Kit	"Skip the grocery store" hook in 8/12 ads
Brand B	7	Software, Subscription	Heavy on UGC video, "$1 first week" offer

Common CTAs and hooks:

Pattern	Count	Examples
Sign up CTA	18	…
Shop now CTA	12	…
Price-anchor opener ("From $X/week")	9	…
Founder-story opener	4	…

Recently launched ads (last 7 days):

Page	Started	CTA	Hook	Library URL
Brand A	2026-04-28	Sign up	"Skip the grocery run this week"	<ad_library_url>

Lead list (enriched only):

Page	Email	Website	Followers	Active ads
Brand A	hello@a.com	a.com	12K	7

Phase 5 — Recurring monitoring (optional)

If the user wants ongoing tracking:

1. Save the query, country, and active_status settings.
2. Re-run weekly with period="last7d".
3. Brief becomes a delta report — new ads since the last run, advertisers that changed posting cadence, CTA / offer shifts.

This is when competitor-intel becomes the better skill — it handles multi-source diffing across many surfaces, not just Meta ads.

Output standards

• Always cite the ad_library_url for any specific ad referenced in the brief — the user can click through to verify.
• Aggregate before quoting. Don't paste raw ad bodies; extract the pattern and quote 1–2 representative examples.
• Mark interpretation explicitly. "Observation: 8 of 10 top advertisers use a 'first week free' offer. Possible interpretation: …".
• Note the time window. Every brief should state the search query, country, and date range it was generated from.