Facebook Ads Library Scraper

sfoln/facebook-ads-search · Social media, Lead generation, Ecommerce On request

Search the Meta Ad Library (Facebook and Instagram) by keyword, page ID or company: one row per ad with text, CTA, landing URL, images, videos, dates, platforms and, where Meta discloses them, spend and impressions. $1 per 1,000 ads + $0.004 per page.

Request access Run it$1 / 1,000 facebook ad, more below

About

What it does

Facebook Ads Library Scraper searches the Meta Ad Library (Facebook, Instagram, Messenger, Audience Network) by keyword, Facebook page ID or company name and returns one clean dataset record per ad: ad archive ID, advertiser page, start/end dates, active status, platforms, ad text, headline, call to action, landing URL, media type, image and video URLs and, where Meta discloses it, impressions, spend and targeted countries. Filter by country, active status, media type, political/issue ads, language and date range. Built for competitor research, creative inspiration, ad monitoring, agencies and AI agents.

Price

Price per delivered record

Event	Price	Per 1,000	Charged for
Facebook ad `facebook-ad`	$0.001	$1 / 1,000	Charged once per ad record delivered from the Meta Ad Library (recordType ad). Duplicates, query summary rows and failed requests are not charged.
Ad Library page `facebook-ads-query`	$0.004	$4 / 1,000	Charged once per Ad Library results page fetched for a query (a page holds up to ~30 ads). A page without new ads is charged only when the upstream provider billed it. Failed requests are not charged.

Apify free plan: up to 10 items per run. Paid plans have no per-run cap; set maxTotalChargeUsd to cap spend.

Run

Call it from code, an agent or the Console

This API is private on Apify for now. Email us and we will publish it for you, usually within two working days. The calls below work once it is public. contact@sfoln.com

curl · synchronous run, rows in the response

curl -X POST "https://api.apify.com/v2/actors/sfoln~facebook-ads-search/run-sync-get-dataset-items" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"queries":["running shoes"],"maxAdsPerQuery":10,"country":"US"}'

mcp.json · hosted Apify MCP server

{
  "mcpServers": {
    "apify": {
      "type": "http",
      "url": "https://mcp.apify.com?tools=sfoln/facebook-ads-search"
    }
  }
}

asynchronous run · for large batches

POST https://api.apify.com/v2/actors/sfoln~facebook-ads-search/runs?maxTotalChargeUsd=1
GET  https://api.apify.com/v2/actor-runs/{runId}            # until status is SUCCEEDED
GET  https://api.apify.com/v2/datasets/{defaultDatasetId}/items?format=json

Authenticate with an Apify API token. MCP clients can instead sign in with OAuth when prompted. Example prompt for an agent: Find 20 active Facebook and Instagram ads in the US that mention "running shoes" and summarize their headlines, calls to action and landing pages.

Input

Input fields

Search the Meta Ad Library by keyword, Facebook page ID or company name. Each query returns one dataset record per ad plus one summary record.

Field	Type	Default	Meaning
`queries`	`array`	—	Search keywords Keywords to search the Ad Library for (ad text match), one per line. Accounts on the Apify free plan can process up to 10 queries per run (keywords, page IDs and company names together).
`pageIds`	`array`	—	Facebook page IDs Numeric Facebook page IDs, or Ad Library URLs containing view_all_page_id=…, to list all ads of that page.
`companyNames`	`array`	—	Company names Advertiser / company names; the upstream resolves the name to its Ad Library page (a page ID is more precise).
`maxAdsPerQuery`	`integer`	`50`	Max ads per query Maximum ads returned per keyword, page or company (1–500). Ads are fetched in pages of up to ~30. Range 1–500.
`country`	`string`	`"ALL"`	Country 2-letter country code where the ads were delivered (e.g. US, GB, DE), or ALL.
`status`	`string`	`"ACTIVE"`	Ad status Only active ads, only inactive ads, or both. One of `"ACTIVE"`, `"INACTIVE"`, `"ALL"`.
`mediaType`	`string`	`"ALL"`	Media type Filter by creative type. MEME means image + text. One of `"ALL"`, `"IMAGE"`, `"VIDEO"`, `"MEME"`, `"IMAGE_AND_MEME"`, `"NONE"`.
`adType`	`string`	`"all"`	Ad category (keyword search only) All ads, or only political and social-issue ads. One of `"all"`, `"political_and_issue_ads"`.
`searchType`	`string`	`"keyword_unordered"`	Keyword matching (keyword search only) Match any of the words, or the exact phrase. One of `"keyword_unordered"`, `"keyword_exact_phrase"`.
`sortBy`	`string`	`"total_impressions"`	Sort by Most impressions first, or most recent first. One of `"total_impressions"`, `"relevancy_monthly_grouped"`.
`language`	`string`	—	Language Optional 2-letter language code of the ad (EN, ES, FR…).
`startDate`	`string`	—	Shown from (YYYY-MM-DD) Optional: only ads with impressions on or after this date.
`endDate`	`string`	—	Shown until (YYYY-MM-DD) Optional: only ads with impressions on or before this date.
`maxQueries`	`integer`	`100`	Max queries Safety cap on keywords + pages + companies processed in this run. Range 1–1000.
`concurrency`	`integer`	`4`	Concurrency Queries processed in parallel (1–8). Range 1–8.
`itemTimeoutSecs`	`integer`	`600`	Time limit per query (seconds) Pagination for one keyword, page or company stops cleanly shortly before this limit (60–3600). Raise it for very large per-query limits. Range 60–3600.
`includeRaw`	`boolean`	`false`	Include raw upstream response Attach the unmodified upstream ad object to each ad record under `raw` (larger output).

Example input

{
  "queries": [
    "running shoes"
  ],
  "maxAdsPerQuery": 10,
  "country": "US"
}

Output

One record per input item

Records land in the run's dataset; a synchronous call returns them directly. Each has a status (ok is charged; everything else is free) and a charged flag. The run's OUTPUT record totals items and charges.

Field	Type	Meaning
`input`	`string \| object`	Input The input query this record belongs to.
`recordType`	`string`	Row type ad (one per ad, charged facebook-ad) \| query (one summary per query, free).
`status`	`string`	Status ok \| not_found \| error \| skipped_invalid \| skipped_budget \| skipped_free_plan
`charged`	`boolean`	Charged Whether this record incurred a pay-per-event charge.
`chargedEvent`	`string`	Charged event Pay-per-event event charged for this record.
`source`	`string`	Source Upstream data source (scrapecreators = ScrapeCreators API over the public ad library).
`fetchedAt`	`string`	Fetched at ISO timestamp.
`error`	`object`	Error code / message when status is not ok.
`warnings`	`array`	Warnings Non-fatal notes (e.g. stopped early).
`query`	`string \| null`	Query Keyword, page ID or company name the row belongs to.
`queryType`	`string \| null`	Query type keyword \| page \| company.
`position`	`integer \| null`	Position 1-based position of the ad within the query results.
`adArchiveId`	`string \| null`	Ad archive ID Meta Ad Library ID of the ad.
`adLibraryUrl`	`string \| null`	Ad Library URL Public Ad Library link to the ad (snapshot).
`pageId`	`string \| null`	Page ID Advertiser's Facebook page ID.
`pageName`	`string \| null`	Page name Advertiser's page name.
`pageUrl`	`string \| null`	Page URL Advertiser's Facebook page.
`pageLikeCount`	`integer \| null`	Page likes Page like count at fetch time.
`pageCategories`	`array`	Page categories Page categories.
`isActive`	`boolean \| null`	Active Ad is currently running.
`startDate`	`string \| null`	Start date ISO date the ad started running.
`endDate`	`string \| null`	End date ISO date the ad stopped (or last seen) running.
`totalActiveTimeSecs`	`integer \| null`	Active time (s) Total active time in seconds when reported.
`platforms`	`array`	Platforms Publisher platforms: facebook, instagram, audience_network, messenger, threads.
`adText`	`string \| null`	Ad text Primary text (body) of the ad; first card's body for multi-version ads.
`headline`	`string \| null`	Headline Link title / headline.
`linkDescription`	`string \| null`	Link description Text under the headline.
`linkUrl`	`string \| null`	Landing URL Destination link.
`displayUrl`	`string \| null`	Display URL Domain shown on the ad (caption).
`ctaText`	`string \| null`	CTA text Call-to-action button text.
`ctaType`	`string \| null`	CTA type Call-to-action code, e.g. SHOP_NOW, LEARN_MORE.
`mediaType`	`string \| null`	Media type image \| video \| multi_images \| carousel \| dco \| dpa \| text …
`imageUrls`	`array`	Image URLs Creative images (original resolution where available).
`videoUrls`	`array`	Video URLs Creative videos (HD where available).
`thumbnailUrl`	`string \| null`	Thumbnail Video preview image or resized first image.
`cardCount`	`integer \| null`	Cards Number of carousel / version cards.
`collationCount`	`integer \| null`	Versions Number of ad versions grouped under this ad.
`languages`	`array`	Languages Ad languages when the library reports them.
`impressionsText`	`string \| null`	Impressions Impressions range text when Meta discloses it (political / EU ads).
`reachEstimate`	`integer \| null`	Reach estimate Estimated reach when disclosed.
`spendLower`	`number \| null`	Spend (lower) Lower spend bound when disclosed (political ads).
`spendUpper`	`number \| null`	Spend (upper) Upper spend bound when disclosed.
`currency`	`string \| null`	Currency Currency of the spend bounds.
`targetedCountries`	`array`	Targeted countries Targeted / reached or political countries when reported.
`targetsEu`	`boolean \| null`	Targets EU EU transparency data present (ad details only).
`euTotalReach`	`integer \| null`	EU reach Total EU reach (ad details only).
`audienceAgeMin`	`integer \| null`	Audience age min Targeted minimum age (ad details only).
`audienceAgeMax`	`integer \| null`	Audience age max Targeted maximum age (ad details only).
`audienceGender`	`string \| null`	Audience gender Targeted gender (ad details only).
`audienceLocations`	`array`	Audience locations Targeted locations (ad details only).
`payers`	`array`	Payers Who paid for the ad (EU transparency; ad details only).
`beneficiaries`	`array`	Beneficiaries Who benefits from the ad (EU transparency; ad details only).
`reachBreakdown`	`array`	Reach breakdown EU reach by country / age range / gender (ad details only).
`adsDelivered`	`integer \| null`	Ads delivered Ads delivered for this query (summary rows).
`pagesFetched`	`integer \| null`	Pages fetched Upstream pages fetched (summary rows).
`queryFeesCharged`	`integer \| null`	Page fees charged facebook-ads-query events charged for this query (summary rows).
`totalResults`	`integer \| null`	Total results Total matching ads reported by the library (summary rows; capped at 50,001 by Meta).
`stopReason`	`string \| null`	Stop reason limit \| end \| budget \| max_pages \| deadline \| error \| empty_pages (summary rows).

Example record

{
  "input": {
    "kind": "page",
    "value": "15087023444"
  },
  "recordType": "ad",
  "query": "15087023444",
  "queryType": "page",
  "position": 1,
  "adArchiveId": "1212560900568826",
  "adLibraryUrl": "https://www.facebook.com/ads/library?id=1212560900568826",
  "pageId": "15087023444",
  "pageName": "Nike",
  "pageUrl": "https://facebook.com/nike",
  "pageLikeCount": 37497718,
  "pageCategories": [
    "Ropa deportiva"
  ],
  "isActive": true,
  "startDate": "2025-06-17T07:00:00.000Z",
  "endDate": "2025-06-18T07:00:00.000Z",
  "platforms": [
    "facebook"
  ],
  "adText": "Que el frío no te detenga. Explora la colección de invierno con estilo y actitud Nike. 🧥",
  "headline": "Look de invierno activado",
  "linkUrl": "https://fb.com/canvas_doc/569658969305127",
  "displayUrl": "fb.com",
  "ctaText": "Learn more",
  "ctaType": "LEARN_MORE",
  "mediaType": "video",
  "imageUrls": [],
  "videoUrls": [
    "https://video.xx.fbcdn.net/…hd.mp4"
  ],
  "thumbnailUrl": "https://scontent.xx.fbcdn.net/…preview.jpg",
  "impressionsText": null,
  "spendLower": null,
  "spendUpper": null,
  "targetedCountries": [],
  "status": "ok",
  "charged": true,
  "chargedEvent": "facebook-ad",
  "source": "scrapecreators",
  "fetchedAt": "2026-10-14T10:00:00.000Z"
}

Machine-readable

This page for agents

/actors/facebook-ads-search.json — this API as JSON
/actors/facebook-ads-search.md — this API as Markdown
/catalog.json — the whole catalogue