Facebook 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.
What is the Facebook 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.
curl -X GET 'https://api.parse.bot/scraper/42625882-3319-47c3-ba27-9c09ac645ee0/search_ads?ad_type=all&country=AT&page_id=2214120985581210&media_type=all&active_status=all' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace facebook-com-ad-library-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Facebook Ad Library SDK — search ads, inspect details, explore collations."""
from parse_apis.Facebook_Ad_Library_API import (
FacebookAdLibrary, ActiveStatus, Country, MediaType, NotFoundError
)
client = FacebookAdLibrary()
# Search all ads for a specific page with filters
page = client.page("2214120985581210")
for ad in page.search_ads(active_status=ActiveStatus.ALL, country=Country.AT, limit=3):
print(ad.ad_archive_id, ad.page_name, ad.is_active, ad.start_date)
# Drill into the first ad's details — EU transparency, payer/beneficiary
ad = page.search_ads(media_type=MediaType.ALL, limit=1).first()
if ad:
details = ad.details(country=Country.AT)
print(details.advertiser.page_name, details.advertiser.likes)
print("Targets EU:", details.targets_eu)
if details.eu_transparency:
print("EU Reach:", details.eu_transparency.eu_total_reach)
for loc in details.eu_transparency.location_audience:
print(f" {loc.name} (excluded={loc.excluded})")
# Explore a collation group — all creative variants of a grouped ad
if ad and ad.collation_id:
for variant in client.pages.get_collation(collation_id=ad.collation_id, country=Country.AT, limit=3):
print(variant.ad_archive_id, variant.display_format, variant.title)
# Typed error handling
try:
bad_page = client.page("0000000000000000")
bad_page.search_ads(limit=1).first()
except NotFoundError as exc:
print(f"Not found: {exc}")
print("exercised: page.search_ads / ad.details / pages.get_collation / NotFoundError")
Search Facebook Ad Library for ads by page ID or search term. Returns ads with their creative content, dates, platforms, and metadata. Supports cursor-based pagination via after_cursor. 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', 'HK', '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. |
| after_cursor | string | Pagination cursor from a previous response's end_cursor field. Omit or empty string for first page. |
| 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": "Sample card body text",
"title": "Card title",
"cta_text": "Learn More",
"cta_type": "LEARN_MORE",
"link_url": "https://example.com"
}
],
"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 API
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.
The Facebook API is a managed, monitored endpoint for de-de.facebook.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when de-de.facebook.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official de-de.facebook.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- 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 | 100 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.