See competitors' Facebook and Instagram ads from the Meta Ad Library
Query the public Meta Ad Library using thelastapi's unified API or CLI to inspect competitor ad copy, creative, dates, and active platforms.
On this page 7 sections
You can query the public Meta Ad Library directly using the ads.library action in thelastapi via the CLI, HTTP API, or Node.js SDK. Pass an advertiser's page name, Facebook page URL, or search keywords to inspect active and historical ads across Facebook, Instagram, Messenger, and Threads without maintaining separate scrapers or individual platform tokens.
Understanding your competitors' messaging, creative choices, and campaign duration offers clear visibility into what offers are running in your market. This guide shows how to fetch competitor ads, filter by country and media format, and parse the structured output.
How the Meta Ad Library action works
The ads.library action pulls data from the public Meta Ad Library. It lets you query ads by a specific brand or by search terms contained within the ad copy.
Each call returns a list of matching ads along with metadata:
- Creative assets (image links and video URLs with thumbnails)
- Ad copy, titles, destination links, and call-to-action (CTA) text
- Active status and running dates (
started_at,ended_at) - Target platforms (Facebook, Instagram, Messenger, Threads)
- Direct link to the Ad Library snapshot (
snapshot_url) - Spend ranges and impression estimates (available for political ads and ads served in the EU)
Just like when you scrape a website to markdown with one API call, this web data action runs synchronously, returns structured JSON, logs to your project history, and reports its cost in micro-USD.
Querying ads from the CLI
The quickest way to check a competitor's active campaigns is with the vibiz ads command in your terminal.
To inspect a brand by its Facebook page URL or brand name:
# Query by Facebook page URL
vibiz ads "https://www.facebook.com/nike" --country US --limit 20
# Query by advertiser page name
vibiz ads Nike --pageYou can also search across all advertisers for specific keywords in the ad text, or filter down to video creatives:
# Find any advertiser running video ads mentioning "protein bars"
vibiz ads "protein bars" --media video
# Include stopped ads as well as active ones
vibiz ads "protein bars" --allRunning the action with HTTP or the Node.js SDK
For automated tracking, competitor dashboards, or feeding creative intelligence to an AI agent, you can call ads.library through plain HTTP or the @vibiz/app SDK. You can also view details in the Web data docs.
Making an HTTP request
Send a POST request to /v1/actions/ads.library:
curl https://thelastapi.dev/v1/actions/ads.library \
-H "Authorization: Bearer $VIBIZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"page": "Nike",
"country": "US",
"limit": 20,
"active": true
}
}'Using the Node.js SDK
If you are developing a Node or Next.js app, import vibiz from @vibiz/app:
import { vibiz } from '@vibiz/app';
const { output, cost_micro_usd } = await vibiz.actions.run('ads.library', {
page: 'Nike',
country: 'US',
limit: 20,
active: true,
});
for (const ad of output.ads) {
console.log(`Ad ID: ${ad.id}`);
console.log(`Platforms: ${ad.platforms.join(', ')}`);
console.log(`Copy: ${ad.body}`);
console.log(`CTA: ${ad.cta} -> ${ad.link}`);
}Input parameters and output structure
The ads.library action requires either a search query or a specific advertiser page. You cannot provide both, and leaving both empty triggers an invalid_request error.
Input fields
| Field | Type | Default | Description |
|---|---|---|---|
query | string | none | Search for words inside ad text. Used if page is omitted. |
page | string | none | The advertiser: page name, page URL, Ad Library URL, or page ID. |
country | string | ALL | Country code to filter results (US, DE, ALL, etc.). |
active | boolean | true | When true, filters only to currently running ads. |
media | string | all | Filter by creative type: all, image, or video. |
limit | integer | 20 | Number of results to return (range: 1 to 100). |
Output fields
A successful response returns an action_result object:
{
"object": "action_result",
"action": "ads.library",
"output": {
"library_url": "https://www.facebook.com/ads/library/?...",
"ads": [
{
"id": "1234567890",
"page_name": "Nike",
"page_url": "https://www.facebook.com/nike",
"started_at": "2025-01-10T12:00:00Z",
"ended_at": null,
"active": true,
"platforms": ["facebook", "instagram"],
"body": "Step into comfort with the newest releases.",
"title": "Shop the New Collection",
"link": "https://nike.com/new-releases",
"cta": "Shop Now",
"images": ["https://..."],
"videos": [
{
"url": "https://...",
"thumbnail": "https://..."
}
],
"snapshot_url": "https://www.facebook.com/ads/library/?id=1234567890",
"spend": null,
"impressions": null
}
]
},
"cost_micro_usd": 98000,
"run_id": "arun_123",
"console_url": "https://thelastapi.dev/web-data?action=ads.library&run=arun_123"
}Note that spend and impressions return ranges only for EU-targeted ads and political ads, matching what Meta's Ad Library publicly discloses.
Checking execution history and costs
Web data actions charge for external data retrieval plus a standard margin (30% on web data). For ads.library, retrieving an ad set averages about half a cent per ad found.
Because ad library calls query live external repositories, complex queries or large result limits can take between 60 and 150 seconds. If an operation exceeds this duration, it returns a 503 error with provider_unavailable and details.reason: "timeout". Reduce your limit value if you encounter timeouts on broad queries.
Every run is logged under your account and accessible from the CLI:
# View recent ad library runs
vibiz runs --action ads.library --since 1d
# Retrieve full output from a specific past run
vibiz runs arun_123 --jsonCached runs save budget: AI agents can check vibiz_action_runs before re-fetching an advertiser's active campaigns.
Combining competitor ad data with SEO analysis
Ad copy reveals what messaging competitors pay to put in front of their audiences. You can pair this research with organic search insights:
- Use keyword ideas with volume and difficulty (
vibiz seo ideas "<term>") to evaluate the organic demand for the phrases competitors use in their ad titles. - Run an on-page SEO audit (
vibiz seo audit <url>) on the landing page destination URL (link) extracted from their ad to see how their conversion funnel is optimized. - Once you define your own marketing strategy, you can schedule and post to Instagram, TikTok and LinkedIn from one API using the same unified key.
To explore all supported parameters and view schemas for related data tools like Google Maps searches, reviews, and domain research, visit the Web data documentation.
Frequently asked questions
Why are spend and impression metrics null for some ads?
Meta only publishes spend and impression numbers for political ads and ads displayed within the European Union. For commercial ads outside the EU, the Ad Library returns creative, copy, dates, and platforms, but spend and impressions remain null.
What is the maximum number of ads I can retrieve in a single call?
The `limit` parameter supports up to 100 ads per request, with a default of 20. If your request approaches the execution timeout limit on large queries, specify a smaller limit.
Can I use ads.library to monitor my own ads?
Yes, you can pass your own Facebook page URL, page name, or page ID in the `page` field to pull all active creatives and verify how your ads appear across Facebook, Instagram, Messenger, and Threads.