facebook.com Ad Library APIde-de.facebook.com ↗
Search Facebook's Ad Library by page ID or keyword. Extract ad creatives, targeting data, EU transparency metrics, and payer/beneficiary info via 3 endpoints.
curl -X GET 'https://api.parse.bot/scraper/42625882-3319-47c3-ba27-9c09ac645ee0/search_ads?country=US' \ -H 'X-API-Key: $PARSE_API_KEY'
Search Facebook Ad Library for ads by page ID or search term. Returns ads with their creative content, dates, platforms, and metadata. At least one of page_id or search_term must be provided.
| Param | Type | Description |
|---|---|---|
| ad_type | string | Filter by ad type: 'all', 'political_and_issue_ads'. |
| country | string | ISO country code to filter ads (e.g., 'AT', 'DE', 'US'). |
| page_id | string | Facebook page ID to get all ads for (e.g., '2214120985581210'). Either page_id or search_term must be provided. |
| media_type | string | Filter by media type: 'all', 'image', 'meme', 'video', 'none'. |
| search_term | string | Keyword to search ads for. Either page_id or search_term must be provided. |
| active_status | string | Filter by active status: 'all', 'active', 'inactive'. |
{
"type": "object",
"fields": {
"ads": "array of ad objects containing ad_archive_id, page_id, page_name, is_active, start_date, end_date, publisher_platforms, collation_id, body_text, title, link_url, images, videos, cards, and more",
"end_cursor": "string pagination cursor for next page, or empty string",
"total_count": "integer total number of ads matching the query",
"ads_returned": "integer number of ads in this response",
"has_next_page": "boolean indicating if more results are available"
},
"sample": {
"data": {
"ads": [
{
"cards": [
{
"body": "Du willst wissen...",
"title": "Die aktuellen Top 5 Winning Creatives von SNOCKS",
"link_url": "https://results.strongermarketing.de/snocks-masterclass/"
}
],
"title": "{{product.name}}",
"images": [],
"videos": [],
"page_id": "2214120985581210",
"end_date": "2026-01-20",
"link_url": "https://results.strongermarketing.de/snocks-masterclass/",
"body_text": "{{product.brand}}",
"is_active": false,
"page_name": "Stronger GmbH",
"start_date": "2025-10-01",
"collation_id": "1340335444416440",
"ad_archive_id": "1713310646043157",
"display_format": "DCO",
"collation_count": 2,
"publisher_platforms": [
"FACEBOOK",
"INSTAGRAM",
"AUDIENCE_NETWORK"
]
}
],
"end_cursor": "",
"total_count": 9,
"ads_returned": 9,
"has_next_page": false
},
"status": "success"
}
}About the facebook.com Ad Library API
The Facebook Ad Library API provides 3 endpoints for retrieving ad data from Meta's public Ad Library, covering creative content, audience targeting breakdowns, and EU transparency disclosures. The search_ads endpoint accepts a page ID or search term and returns ad archive IDs, publisher platforms, active status, and pagination cursors. Two companion endpoints retrieve per-ad detail records and collation groups of related ad versions.
What the API Covers
The API surfaces data from Facebook's Ad Library — a public transparency tool that catalogs ads running across Meta platforms. The three endpoints map to the three main data access patterns in the library: broad search, single-ad detail, and collation-group retrieval. All endpoints accept an ISO country code (country param) to scope results to a specific market such as AT, DE, or US.
search_ads
search_ads is the entry point. Supply either a page_id (e.g., 2214120985581210) or a search_term keyword. Optional filters include ad_type (all or political_and_issue_ads), media_type (image, video, meme, none, or all), and active_status (active, inactive, or all). Each item in the returned ads array includes ad_archive_id, page_id, page_name, is_active, start_date, end_date, publisher_platforms, and a collation_id. The response also returns total_count, ads_returned, has_next_page, and an end_cursor string for paginating through large result sets.
get_ad_details and get_ad_collation
get_ad_details takes an ad_archive_id and page_id pair and returns an advertiser object with fields including page_category, likes, ig_username, ig_followers, entity_type, and about. For ads targeting the EU, an eu_transparency object provides location_audience, gender_audience, age_audience, eu_total_reach, and an age_country_gender_reach_breakdown. The endpoint also returns payer_beneficiary records and violation_types arrays, plus an is_ad_taken_down flag.
get_ad_collation resolves a collation_id from search results into the full set of related ad versions Facebook groups together. It returns the same ad object schema as search_ads, plus is_complete, total_count, and both forward_cursor and backward_cursor for bidirectional pagination through the group.
- Track all active ads from a competitor's Facebook page using
search_adswith theirpage_id - Monitor political and issue advertising in a specific country by filtering
ad_type=political_and_issue_adswith an ISO country code - Audit EU-targeted ad campaigns by extracting
eu_transparencybreakdowns including age, gender, and location audience data - Identify payer/beneficiary relationships in political ads using the
payer_beneficiaryarray fromget_ad_details - Enumerate all creative variants of a single ad campaign via
get_ad_collationusing acollation_id - Check whether specific ads have been taken down or flagged using
is_ad_taken_downandviolation_typesfields - Build a cross-market ad intelligence feed by running
search_adsacross multiple country codes for the same page
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Facebook have an official developer API for its Ad Library?+
What does `get_ad_details` return that `search_ads` does not?+
get_ad_details returns the full advertiser object (including Instagram follower count, page category, and entity type), the eu_transparency breakdown with age/gender/location audience data and reach figures, payer_beneficiary records, violation_types, and the is_ad_taken_down flag. The search_ads endpoint returns only top-level metadata needed to identify and paginate ads.How does pagination work across the endpoints?+
search_ads returns a string end_cursor and a has_next_page boolean; pass the cursor back in your next request to retrieve the following page. get_ad_collation returns separate forward_cursor and backward_cursor strings, enabling bidirectional navigation through a collation group. Both cursors are empty string or null when no further pages exist.Does the API return ad spend or impression count data?+
eu_total_reach in the EU transparency object, but per-ad spend figures and granular impression counts are not part of any response field. You can fork this API on Parse and revise it to add an endpoint targeting spend or impression data if Meta surfaces it for your target region.Is EU transparency data available for all ads?+
eu_transparency object and targets_eu flag are only populated when an ad targets the EU. For ads outside EU scope, those fields will be absent or empty. Coverage also depends on whether the advertiser has filed the required disclosures — some fields within the object may be null even when targets_eu is true.