Facebook APIfacebook.com ↗
Search and retrieve Meta Ad Library data across Facebook, Instagram, and Messenger. Get ad creatives, spend ranges, impressions, and political transparency info.
What is the Facebook API?
This API exposes 3 endpoints for querying Meta's Ad Library, covering ads running across Facebook, Instagram, Messenger, and Audience Network. The search_ads endpoint accepts keyword or advertiser name queries and returns up to ~30 ads per request with creative details, spend ranges, and funding entity disclosures. Individual ad lookup and page-level ad enumeration are also available, making it straightforward to pull structured data for any advertiser or ad ID.
curl -X GET 'https://api.parse.bot/scraper/d992d152-9f1b-493e-80a4-5aec30d9b03c/search_ads?query=nike&country=US&active_status=active&ad_type=all&media_type=all&search_type=keyword_unordered' \ -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-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, drill into pages, fetch details."""
from parse_apis.Facebook_Ad_Library_API import AdLibrary, AdType, ActiveStatus, AdNotFound
client = AdLibrary()
# Search for ads by keyword, limit total items fetched
for ad in client.ads.search(query="nike", ad_type=AdType.ALL, limit=3):
print(ad.page_name, ad.display_format, ad.body_text[:60])
# Drill into a specific advertiser's page to list their ads
page = client.page(page_id="15087023444")
for ad in page.ads.list(active_status=ActiveStatus.ACTIVE, limit=3):
print(ad.ad_archive_id, ad.title, ad.publisher_platforms)
# Fetch a single ad by ID with full details
first_ad = client.ads.search(query="election", ad_type=AdType.POLITICAL_AND_ISSUE, limit=1).first()
if first_ad:
try:
detail = client.ads.get(ad_id=first_ad.ad_archive_id)
print(detail.page_name, detail.spend, detail.impressions)
if detail.funding_entity:
print(detail.funding_entity.fec_committee_id, detail.funding_entity.address)
except AdNotFound as exc:
print(f"Ad removed: {exc.ad_id}")
print("exercised: ads.search / page.ads.list / ads.get (with AdNotFound handling)")
Search the Facebook Ad Library by keyword or advertiser name. Returns up to ~30 ads per request matching the query, sorted by total impressions descending. For political/issue ads, results include spend ranges, impression counts, and funding entity disclosures. Results are auto-iterated; pass limit to cap total items fetched.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Keyword or advertiser name to search for in the Ad Library. |
| ad_type | string | Category of ads to search. |
| country | string | ISO 2-letter country code for the ad library region (e.g. US, GB, DE, BR). |
| media_type | string | Filter by media type. Accepted values: all, image, meme, video, none. |
| search_type | string | Type of search matching. Accepted values: keyword_unordered, keyword_exact_phrase. |
| active_status | string | Filter by ad active status. |
| forward_cursor | string | Opaque cursor for fetching the next page of results. Obtain from the page_info.end_cursor field of a previous response. |
{
"type": "object",
"fields": {
"ads": "array of ad objects with creative details, spend, and transparency data",
"page_info": "object with end_cursor and has_next_page for cursor pagination",
"total_count": "integer total matching ads"
},
"sample": {
"data": {
"ads": [
{
"spend": null,
"title": "Nike: Shoes, Apparel, Stories",
"byline": null,
"images": [
"https://scontent.fbcdn.net/example.jpg"
],
"videos": [],
"caption": "itunes.apple.com",
"page_id": "15087023444",
"cta_text": "Install now",
"currency": null,
"end_date": 1782284400,
"link_url": "http://itunes.apple.com/app/id1095459556",
"body_text": "Celebra tu cumpleanos con Nike",
"is_active": true,
"page_name": "Nike",
"categories": [
"UNKNOWN"
],
"start_date": 1773730800,
"impressions": null,
"ad_archive_id": "1869276447125570",
"display_format": "DPA",
"reach_estimate": null,
"page_categories": [
"Sportswear"
],
"disclaimer_label": null,
"page_profile_uri": "https://www.facebook.com/nike/",
"publisher_platforms": [
"FACEBOOK",
"INSTAGRAM",
"AUDIENCE_NETWORK"
],
"page_profile_picture_url": "https://scontent.fbcdn.net/example_60x60.jpg",
"contains_digital_created_media": false
}
],
"page_info": {
"end_cursor": "AQHSNHmtWwCCS",
"has_next_page": true
},
"total_count": 50001
},
"status": "success"
}
}About the Facebook API
What the API Covers
The API surfaces data from Meta's public Ad Library, which tracks ads running on Facebook, Instagram, Messenger, and Audience Network. All three endpoints return ad objects containing creative content (images, videos, captions, titles), CTA text, landing page URLs, page IDs, and platform distribution. For political and issue ads, results also include spend ranges (e.g. $125K – $150K), impression counts, and funding entity disclosures required by Meta's political ad transparency rules.
Endpoints and Parameters
search_ads accepts a required query string and optional filters: ad_type, country (ISO 2-letter code), media_type (all, image, meme, video, none), search_type (keyword_unordered or keyword_exact_phrase), and active_status. Results are sorted by total impressions descending and paginated via a page_info object that includes end_cursor and has_next_page. search_page_ads works identically but scopes results to a specific Facebook page using a numeric page_id. get_ad_details takes a single ad_id and returns the full ad object for that specific creative, including end_date as a Unix epoch timestamp and currency.
Coverage and Limitations
Spend and impression figures are only populated for political and issue ads — Meta does not expose spend data for standard commercial ads in its public Ad Library. The country parameter controls which regional Ad Library is queried; not all ad types or transparency fields are available in every country. Pagination is cursor-based: use end_cursor from page_info to fetch subsequent pages of results.
The Facebook API is a managed, monitored endpoint for facebook.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when 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 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?+
- Monitor a competitor's active Facebook and Instagram ad creatives by querying their page ID with
search_page_ads - Track political ad spending by filtering
search_adswithad_type=political_and_issue_adsto surface spend ranges and funding disclosures - Build an ad creative library by collecting images, videos, captions, and CTA text from
search_adsresults - Audit a specific ad by ID using
get_ad_detailsto retrieve its full creative content, link URL, and impression data - Research advertiser activity in a specific country by passing a
countrycode to any endpoint - Detect new ad launches for a brand by polling
search_page_adswithactive_status=activefor a given page ID - Analyze media format trends by filtering
search_adswith themedia_typeparameter across a keyword set
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Meta have an official developer API for the Ad Library?+
Does `search_ads` return spend data for all ads?+
spend field returns null. The ad_type parameter lets you filter specifically for political_and_issue_ads to retrieve results where spend data is present.Does the API return audience targeting details — age, gender, or geographic targeting used for a specific ad?+
How does pagination work across endpoints?+
page_info object containing end_cursor (a string) and has_next_page (boolean). When has_next_page is true, pass the end_cursor value as a cursor parameter in the next request to retrieve the following batch of results. Each batch contains up to ~30 ads.Is Ad Library data available for all countries?+
country parameter is supported by all three endpoints and accepts any ISO 2-letter country code. However, Meta's Ad Library coverage and the fields populated — particularly transparency data — vary by region. Political ad disclosures, for example, are most complete for US (US) and EU member states. Some ad categories or disclosure fields may be absent for less-covered regions.