Meta requires every advertiser on Facebook and Instagram to disclose their running ads publicly, visible to anyone regardless of page follower status. That's the whole premise of the Ad Library: point it at any page and see exactly what they're paying to promote right now. The catch is that it's built for browsing one ad at a time, not for pulling a competitor's full creative history into something you can actually analyze.
That distinction matters more than it sounds. Checking a handful of ads by hand tells you what a competitor is running today. Pulling the whole library — every active ad, every retired one, how long each stayed live — tells you what they've been testing for months and which of it stuck around long enough to matter.
If you're an agent (or building one) reading this rather than a human, the full machine-readable schema for every endpoint below lives at mindcase.co/skills.md.
What makes Ad Library data useful for competitive research?
A handful of fields turn a single ad into a read on strategy:
- Days active. An ad that's been running for months is one a brand keeps paying for, which usually means it's converting. A one-week ad that vanished is a test that didn't work.
- Format and platforms. Whether a brand is leaning on video, carousel, or static image, and whether the same creative is running on Facebook, Instagram, or both, tells you where they think the audience actually is.
- CTA text and destination URL. "Shop Now" into a product page reads differently than "Learn More" into a landing page — it's the difference between a brand harvesting demand and a brand still building it.
- Variant count. Several near-identical ads running at once usually means active A/B testing, not indecision.
A single ad tells you what a brand is trying. A full library tells you what's working well enough to keep funding.
Why doesn't Meta's own Ad Library API cover this?
Meta does publish an official Ad Library API, but its full, free access is scoped to political and social-issue ads — the category Meta is legally required to make transparent. Ordinary commercial ads, the kind most competitive research actually needs, sit outside that guarantee and behind narrower, harder-to-get access.
That's why the public-facing Ad Library website exists at all: it's the one place regular commercial ad data is reliably browsable, just not built for pulling at any volume beyond what a person can click through by hand.
Why doesn't scraping the Ad Library yourself scale?
The website has no documented API behind it, so a scraper means reverse engineering an internal payload structure that shifts whenever Meta changes the UI, with no changelog to warn you. A single IP pulling results at any real volume gets throttled quickly, so you're also maintaining a rotating proxy pool for a page that was never meant to be automated against. And the EU transparency fields — reach estimates, spend ranges, funding entities — only show up for some advertisers in some regions, so a parser built against one ad's shape breaks quietly on the next.
None of this is a one-time cost. It's upkeep on infrastructure that isn't your product, for a page that can change its structure without telling you.
How do you pull a competitor's ad library?
Say you're a DTC skincare brand tracking a competitor's Meta ad activity before you plan next quarter's campaign. Pulling the full picture is two calls: what they're running now, and what they ran before.
How do you get their currently active ads?
curl -X POST "https://api.mindcase.co/v1/data/facebook/ads/run?wait=true" \
-H "Authorization: Bearer $MINDCASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"params": {
"urls": "facebook.com/glossier",
"activeStatus": "active",
"maxResults": 100
}
}'
# $0.005 per adMeta Ads Library API takes one Facebook page URL or
handle per call and returns every currently active ad from it — 21 fields
per row, including headline, body text, CTA, format, platforms, start
date, and how many days it's been running (daysActive). Each row also
carries an advertiser block and, where Meta discloses it, an euReach
and reachBreakdown for that market. Leave isDetailsPerAd on its
default (true) to get both — turning it off returns faster but drops
that context.
How do you see what they've already stopped running?
Set activeStatus to "inactive" instead, same page, same call shape:
curl -X POST "https://api.mindcase.co/v1/data/facebook/ads/run?wait=true" \
-H "Authorization: Bearer $MINDCASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"params": {
"urls": "facebook.com/glossier",
"activeStatus": "inactive",
"maxResults": 100
}
}'
# $0.005 per adA retired ad isn't a failed one by default — some campaigns are seasonal,
some are tied to a launch that already happened. What's worth flagging is
an ad that stopped running after a short daysActive, next to others from
the same page that ran for months. That contrast is the closest thing to
a public performance signal Meta gives you: nobody discloses conversion
rates, but nobody keeps paying for an ad that isn't working, either.
What can't you get from Mindcase?
Two cases.
You don't already know the page. The API takes a specific Facebook page URL or handle as input — there's no keyword mode that searches across every advertiser running ads about a topic. You need to know who you're checking on, the same way you'd need to know a company's name before looking it up in the real Ad Library website.
EU transparency data isn't universal. euReach and reachBreakdown
only populate where Meta actually discloses them, which depends on the
advertiser and the ad's target region. A missing value there isn't a gap
in what Mindcase returns — it's Meta not publishing that figure for that
ad in the first place.
Which endpoint should you use for which job?
| Endpoint | Input | Price | Best for |
|---|---|---|---|
| Meta Ads Library | Facebook page URL or handle | $0.005 / ad | Auditing a specific competitor's current and past ad activity |
FAQ
No. Ad Library data is public by design, and requests run against public page and ad data with no login or connection required.
Yes. Set activeStatus to "inactive" in a separate call to pull ads that are no longer live, alongside the active ones.
$0.005 per ad returned. A 100-ad pull from one competitor's page costs $0.50.
No, not through this endpoint. It takes one page URL or handle per call, so you need to know which advertiser you're checking before you run it.
Set maxResults to 0. That pulls everything matching the activeStatus filter instead of stopping at a fixed count, so a full audit of one competitor is two calls: 0 for active, 0 again for inactive.
