meta-ads-library

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: meta-ads-library
description: Research competitor Facebook and Instagram ads from the Meta Ads Library via the Hyper MCP — search by keyword, pull full ad creative and metadata, enrich with page contact info for lead generation, and surface structured ad-intelligence summaries in chat. Use when the user wants to scrape the Meta Ads Library, spy on competitor ads, monitor new ads in a category, build a lead list from advertisers, or surface creative trends across an industry.
requires_toolkits:
  - meta_ads_library
icon: meta_ads_library
short_description: Search the Meta Ads Library for competitor ads and surface structured ad intelligence.
---

# 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`](../competitor-intel) |
| Generating *new* ad creative based on what you found | [`ad-creative-generation`](../ad-creative-generation) |

## Requirements

- **Hyper MCP installed and connected.** [https://app.hyperfx.ai/mcp](https://app.hyperfx.ai/mcp)
- **Apify integration connected** at [https://app.hyperfx.ai/apps](https://app.hyperfx.ai/apps) — the Meta Ads Library tools run via Apify under the hood.

If `search_facebook_ads` is not in the tool list, stop and tell the user to enable Hyper MCP and connect Apify.

## Tool surface

| Tool | Purpose |
| --- | --- |
| `search_facebook_ads` | Search the Meta Ads Library by keyword. Returns compact results (title, body, CTA, link, page name, dates, platforms). Max 40 per call. |
| `get_facebook_ad_details` | Get full details for a specific ad. Requires both `ad_archive_id` **and** `page_id` — both come from `search_facebook_ads` results. |
| `search_facebook_ads_enriched` | Search + enrich each result with page contact info (email, phone, website). Slower (multiple API calls per result). Max 20 per call. |
| `search_facebook_pages` | Search Facebook pages by category + location (not by keyword). Useful for building a lead list from a vertical. |
| `scrape_facebook_pages` | 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.** `search_facebook_ads` allows `count` up to 40. `search_facebook_ads_enriched` caps at 20 — exceeding this returns an error.
3. **`get_facebook_ad_details` needs two IDs.** Both `ad_archive_id` and `page_id` are required. Both are returned in every `search_facebook_ads` 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 `search_facebook_ads`.
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**