{"id":"3c9b0980-36db-455f-bad4-1b89dac70b9e","slug":"facebook-com-api","name":"facebook.com API","description":"facebook.com API","front_facing_description":"Search and retrieve ads running across Facebook, Instagram, Messenger, and Audience Network to analyze creative content, spending data, and political ad transparency information. Look up specific ads by keyword or page to get comprehensive details about active advertising campaigns.","source_url":"https://www.facebook.com/ads/library/?active_status=active&ad_type=political_and_issue_ads&country=US&is_targeted_country=false&media_type=all&sort_data[mode]=total_impressions&sort_data[direction]=desc","is_authenticated":false,"canonical_scraper_id":"d992d152-9f1b-493e-80a4-5aec30d9b03c","apis":[{"method":"GET","endpoint_name":"search_ads","description":"Search the Facebook Ad Library by keyword or advertiser name. Each call returns one page of ads: the first page (no cursor) carries up to ~30 ads, and subsequent pages fetched with forward_cursor carry up to 30 ads. total_count is the library's count of all matching ads; page_info.end_cursor and page_info.has_next_page reflect the live upstream pagination state - pass end_cursor back as forward_cursor to get the next, non-overlapping page and stop when has_next_page is false (end_cursor is then empty). A forward_cursor that is not a cursor value from a previous response is rejected as invalid input rather than restarting from the first page. A paginated call costs a few extra upstream requests versus the first page. For political/issue ads, results include spend ranges, impression counts, and funding entity disclosures.","input_params":{"query":{"type":"string","required":true,"description":"Keyword or advertiser name to search for in the Ad Library.","domain":{"kind":"open","example":"nike","pattern":".+","generator":{"type":"static","value":"nike"}}},"ad_type":{"type":"string","required":false,"description":"Category of ads to search.","default":"all","enum":"AdType","domain":{"kind":"enum","values":["all","political_and_issue_ads","housing_ads","employment_ads","credit_ads"],"generator":{"type":"enum_pick","strategy":"first"},"exhaustive":true,"source_selector":"radio.ad_category"}},"country":{"type":"string","required":false,"description":"ISO 2-letter country code for the ad library region (e.g. US, GB, DE, BR).","default":"US","domain":{"kind":"open","example":"US","pattern":"^[A-Z]{2}$","generator":{"type":"static","value":"US"}}},"media_type":{"type":"string","required":false,"description":"Filter by media type. Accepted values: all, image, meme, video, none.","default":"all","domain":{"kind":"open","example":"all","pattern":"^(all|image|meme|video|none)$","generator":{"type":"static","value":"all"}}},"search_type":{"type":"string","required":false,"description":"Type of search matching. Accepted values: keyword_unordered, keyword_exact_phrase.","default":"keyword_unordered","domain":{"kind":"open","example":"keyword_unordered","pattern":"^keyword_(unordered|exact_phrase)$","generator":{"type":"static","value":"keyword_unordered"}}},"active_status":{"type":"string","required":false,"description":"Filter by ad active status.","default":"active","enum":"ActiveStatus","domain":{"kind":"enum","values":["active","inactive","all"],"generator":{"type":"enum_pick","strategy":"first"},"exhaustive":true,"source_selector":"filter.active_status"}},"forward_cursor":{"type":"string","required":false,"description":"Opaque continuation cursor for the next page of results. Pass the page_info.end_cursor value from a previous response, unchanged, together with the same filter parameters. Omit or pass an empty string for the first page. Any other value is rejected as invalid input.","domain":{"kind":"open","example":"","pattern":".*","generator":{"type":"static","value":""}}}},"return_schema":{"type":"object","fields":{"ads":"array of ad objects with creative details, spend, and transparency data","page_info":"object with end_cursor (string, empty on the last page) and has_next_page (boolean) reflecting live upstream pagination state","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"}},"initiates_session":false,"price":3,"verification":{"assertions":[{"path":"$.status","op":"equals","value":"success"},{"path":"$.data.ads","op":"array_min_len","value":1},{"path":"$.data.ads[*]","op":"field_present","value":"ad_archive_id"},{"path":"$.data.total_count","op":"not_null"}],"empty_is_valid":false,"recipe_version":1}},{"method":"GET","endpoint_name":"get_ad_details","description":"Retrieve details for a specific ad by its Ad Library ID. Returns a single ad object with full creative content, platform distribution, spend and impression data (for political/issue ads), and funding entity disclosures.","input_params":{"ad_id":{"type":"string","required":true,"description":"The numeric Ad Library ID (e.g. '1869276447125570'). Obtain from search_ads or search_page_ads results.","domain":{"kind":"derived","generator":{"path":"$.data.ads[0].ad_archive_id","type":"derived","from_endpoint":"search_ads"}}},"country":{"type":"string","required":false,"description":"ISO 2-letter country code for the ad library region.","default":"US","domain":{"kind":"open","example":"US","pattern":"^[A-Z]{2}$","generator":{"type":"static","value":"US"}}}},"return_schema":{"type":"object","fields":{"spend":"string or null (e.g. $125K - $150K)","title":"string or null","images":"array of image URLs","videos":"array of video URLs","caption":"string or null","page_id":"string","cta_text":"string or null","currency":"string or null","end_date":"integer unix epoch","link_url":"string or null","body_text":"string","is_active":"boolean","page_name":"string","categories":"array of category strings","start_date":"integer unix epoch","impressions":"string or null (e.g. >1M)","ad_archive_id":"string","display_format":"string or null","funding_entity":"object with FEC/transparency disclosures for political ads, or null","reach_estimate":"string or null","publisher_platforms":"array of platform names"},"sample":{"data":{"spend":"$350K - $400K","title":"Help James fight back","byline":"TALARICO FOR TEXAS","images":[],"videos":["https://video.fbcdn.net/example.mp4"],"caption":"secure.actblue.com","page_id":"1626884974030414","cta_text":"Donate now","currency":"USD","end_date":1771833600,"link_url":"https://secure.actblue.com/donate/jt-ads26","body_text":"","is_active":false,"page_name":"John Doe","categories":["POLITICAL"],"start_date":1771315200,"impressions":">1M","ad_archive_id":"1536277920797773","display_format":"VIDEO","funding_entity":{"email":"user@example.com","phone":"+1 (555) 012-3456","address":"AUSTIN, TX","website":"https://JAMESTALARICO.COM/","submitted_on":"Submitted Dec 26, 2025","fec_committee_id":"C00919084","fec_committee_type":"Senate","fec_treasurer_name":"Jane Doe","authorized_entity_text":"This information was confirmed using a Federal Election Commission (FEC) identification number."},"reach_estimate":">1M","page_categories":["Government Official"],"disclaimer_label":"PAID_FOR_BY","page_profile_uri":"https://www.facebook.com/JamesTalaricoTX/","publisher_platforms":["FACEBOOK","INSTAGRAM"],"page_profile_picture_url":"https://scontent.fbcdn.net/example_60x60.jpg","contains_digital_created_media":false},"status":"success"}},"initiates_session":false,"price":1,"verification":{"assertions":[{"path":"$.status","op":"equals","value":"success"},{"path":"$.data.ad_archive_id","op":"not_null"},{"path":"$.data.page_name","op":"not_null"}],"empty_is_valid":false,"recipe_version":1}},{"method":"GET","endpoint_name":"search_page_ads","description":"List the ads run by a specific Facebook page. Each call returns one page of ads with the same detail as search_ads: the first page (no cursor) carries up to ~30 ads, and subsequent pages fetched with forward_cursor carry up to 30 ads. total_count is the library's count of all matching ads for the page; page_info.end_cursor and page_info.has_next_page reflect the live upstream pagination state - pass end_cursor back as forward_cursor to get the next, non-overlapping page and stop when has_next_page is false (end_cursor is then empty). A forward_cursor that is not a cursor value from a previous response is rejected as invalid input rather than restarting from the first page. A paginated call costs a few extra upstream requests versus the first page. Useful for competitive analysis or monitoring a specific advertiser's activity.","input_params":{"ad_type":{"type":"string","required":false,"description":"Category of ads to filter.","default":"all","enum":"AdType","domain":{"kind":"enum","values":["all","political_and_issue_ads","housing_ads","employment_ads","credit_ads"],"generator":{"type":"enum_pick","strategy":"first"},"exhaustive":true,"source_selector":"radio.ad_category"}},"country":{"type":"string","required":false,"description":"ISO 2-letter country code for the ad library region.","default":"US","domain":{"kind":"open","example":"US","pattern":"^[A-Z]{2}$","generator":{"type":"static","value":"US"}}},"page_id":{"type":"string","required":true,"description":"The numeric Facebook page ID (e.g. '15087023444' for Nike). Obtain from search_ads results or the page's Facebook URL.","domain":{"kind":"derived","generator":{"path":"$.data.ads[0].page_id","type":"derived","from_endpoint":"search_ads"}}},"active_status":{"type":"string","required":false,"description":"Filter by ad active status.","default":"active","enum":"ActiveStatus","domain":{"kind":"enum","values":["active","inactive","all"],"generator":{"type":"enum_pick","strategy":"first"},"exhaustive":true,"source_selector":"filter.active_status"}},"forward_cursor":{"type":"string","required":false,"description":"Opaque continuation cursor for the next page of results. Pass the page_info.end_cursor value from a previous response, unchanged, together with the same filter parameters. Omit or pass an empty string for the first page. Any other value is rejected as invalid input.","domain":{"kind":"open","example":"","pattern":".*","generator":{"type":"static","value":""}}}},"return_schema":{"type":"object","fields":{"ads":"array of ad objects","page_info":"object with end_cursor (string, empty on the last page) and has_next_page (boolean) reflecting live upstream pagination state","total_count":"integer"},"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":"AQHSOuKw2IdbeP7HS","has_next_page":true},"total_count":60},"status":"success"}},"initiates_session":false,"price":3,"verification":{"assertions":[{"path":"$.status","op":"equals","value":"success"},{"path":"$.data.ads","op":"array_min_len","value":1},{"path":"$.data.ads[*]","op":"field_present","value":"ad_archive_id"},{"path":"$.data.total_count","op":"not_null"}],"empty_is_valid":false,"recipe_version":1}}],"sample_inputs":{"search_ads":{"query":"nike","ad_type":"all","country":"US","media_type":"all","search_type":"keyword_unordered","active_status":"active"},"get_ad_details":{"ad_id":"1249043200627555","country":"US"},"search_page_ads":{"ad_type":"all","country":"US","page_id":"15087023444","active_status":"active"}},"prefill_inputs":{"search_ads":{"query":"nike","ad_type":"all","country":"US","media_type":"all","search_type":"keyword_unordered","active_status":"active","forward_cursor":""},"get_ad_details":{"country":"US"},"search_page_ads":{"ad_type":"all","country":"US","active_status":"active","forward_cursor":""}},"last_verified_at":"2026-10-28T07:49:06.224255+00:00","endpoint_health":[{"endpoint_name":"search_ads","status":"healthy","last_checked_at":"2026-10-26T12:04:25.214263+00:00","last_verified_at":"2026-10-26T12:04:25.214263+00:00","recent_runs":[{"at":"2026-10-26T12:04:25.214263+00:00","status":"healthy"},{"at":"2026-10-19T12:03:53.113713+00:00","status":"healthy"},{"at":"2026-10-12T12:00:52.912833+00:00","status":"healthy"},{"at":"2026-10-05T11:04:52.976725+00:00","status":"healthy"},{"at":"2026-09-28T10:04:53.131171+00:00","status":"healthy"}]},{"endpoint_name":"get_ad_details","status":"healthy","last_checked_at":"2026-10-28T07:45:10.958488+00:00","last_verified_at":"2026-10-28T07:45:10.958488+00:00","recent_runs":[{"at":"2026-10-26T12:04:25.214263+00:00","status":"healthy"},{"at":"2026-10-19T12:03:53.113713+00:00","status":"healthy"},{"at":"2026-10-12T12:00:52.912833+00:00","status":"healthy"},{"at":"2026-10-05T11:04:52.976725+00:00","status":"healthy"},{"at":"2026-09-28T10:04:53.131171+00:00","status":"healthy"}]},{"endpoint_name":"search_page_ads","status":"healthy","last_checked_at":"2026-10-28T07:49:06.224255+00:00","last_verified_at":"2026-10-28T07:49:06.224255+00:00","recent_runs":[{"at":"2026-10-26T12:04:25.214263+00:00","status":"healthy"},{"at":"2026-10-19T12:03:53.113713+00:00","status":"healthy"},{"at":"2026-10-12T12:00:52.912833+00:00","status":"healthy"},{"at":"2026-10-05T11:04:52.976725+00:00","status":"healthy"},{"at":"2026-09-28T10:04:53.131171+00:00","status":"healthy"}]}],"sdk_usage_example":{"code":"\"\"\"Walkthrough: Facebook Ad Library SDK — search ads, drill into pages, fetch details.\"\"\"\nfrom parse_apis.facebook_com_api import AdLibrary, AdType, ActiveStatus, AdNotFound\n\nclient = AdLibrary()\n\n# Search for ads by keyword, limit total items fetched\nfor ad in client.ads.search(query=\"nike\", ad_type=AdType.ALL, limit=3):\n    print(ad.page_name, ad.display_format, ad.body_text[:60])\n\n# Drill into a specific advertiser's page to list their ads\nfirst_hit = client.ads.search(query=\"nike\", ad_type=AdType.ALL, limit=1).first()\nif first_hit:\n    page = client.page(page_id=first_hit.page_id.page_id)\n    for ad in page.ads.list(active_status=ActiveStatus.ACTIVE, limit=3):\n        print(ad.ad_archive_id, ad.title, ad.publisher_platforms)\n\n# Fetch a single ad by ID with full details\nif first_hit:\n    try:\n        detail = client.ads.get(ad_id=first_hit.ad_archive_id)\n        print(detail.page_name, detail.spend, detail.impressions)\n        if detail.funding_entity:\n            print(detail.funding_entity.fec_committee_id, detail.funding_entity.address)\n    except AdNotFound as exc:\n        print(f\"Ad removed: {exc.ad_id}\")\n\nprint(\"exercised: ads.search / page.ads.list / ads.get (with AdNotFound handling)\")\n","endpoints":["search_ads","get_ad_details","search_page_ads"],"has_session":false,"shape":"parse_sdk","hover_map":[{"line":7,"col":4,"len":2,"label":"ad: Ad","kind":"variable"},{"line":11,"col":0,"len":9,"label":"first_hit: Ad","kind":"variable"},{"line":12,"col":3,"len":9,"label":"first_hit: Ad","kind":"variable"},{"line":18,"col":3,"len":9,"label":"first_hit: Ad","kind":"variable"},{"line":4,"col":9,"len":9,"label":"AdLibrary — API client","kind":"class"},{"line":7,"col":21,"len":6,"label":"search() → List[Ad]","kind":"method"},{"line":14,"col":8,"len":2,"label":"ad: Ad","kind":"variable"},{"line":7,"col":57,"len":3,"label":"AdType.ALL","kind":"enum-member"},{"line":8,"col":13,"len":9,"label":"page_name: str","kind":"field"},{"line":8,"col":27,"len":14,"label":"display_format: Optional[str]","kind":"field"},{"line":14,"col":23,"len":4,"label":"list() → List[Ad]","kind":"method"},{"line":20,"col":8,"len":6,"label":"detail: Ad","kind":"variable"},{"line":22,"col":18,"len":14,"label":"funding_entity: Optional[FundingEntity]","kind":"field"},{"line":24,"col":11,"len":10,"label":"AdNotFound — error (422): The specified ad_id does not exist or has been removed from the Ad Library","kind":"error"},{"line":7,"col":50,"len":6,"label":"AdType — enum: ALL, CREDIT, EMPLOYMENT, HOUSING, POLITICAL_AND_ISSUE","kind":"enum"},{"line":8,"col":10,"len":2,"label":"ad: Ad","kind":"variable"},{"line":8,"col":24,"len":2,"label":"ad: Ad","kind":"variable"},{"line":8,"col":46,"len":9,"label":"body_text: str","kind":"field"},{"line":11,"col":23,"len":6,"label":"search() → List[Ad]","kind":"method"},{"line":13,"col":49,"len":7,"label":"page_id: str","kind":"field"},{"line":14,"col":55,"len":6,"label":"ActiveStatus.ACTIVE","kind":"enum-member"},{"line":15,"col":17,"len":13,"label":"ad_archive_id: str","kind":"field"},{"line":15,"col":35,"len":5,"label":"title: Optional[str]","kind":"field"},{"line":15,"col":45,"len":19,"label":"publisher_platforms: List[str]","kind":"field"},{"line":20,"col":28,"len":3,"label":"get() → Ad","kind":"method"},{"line":21,"col":21,"len":9,"label":"page_name: str","kind":"field"},{"line":21,"col":39,"len":5,"label":"spend: Optional[str]","kind":"field"},{"line":21,"col":53,"len":11,"label":"impressions: Optional[str]","kind":"field"},{"line":22,"col":11,"len":6,"label":"detail: Ad","kind":"variable"},{"line":8,"col":43,"len":2,"label":"ad: Ad","kind":"variable"},{"line":11,"col":59,"len":3,"label":"AdType.ALL","kind":"enum-member"},{"line":13,"col":41,"len":7,"label":"page_id: Page","kind":"field"},{"line":14,"col":42,"len":12,"label":"ActiveStatus — enum: ACTIVE, ALL, INACTIVE","kind":"enum"},{"line":15,"col":14,"len":2,"label":"ad: Ad","kind":"variable"},{"line":15,"col":32,"len":2,"label":"ad: Ad","kind":"variable"},{"line":15,"col":42,"len":2,"label":"ad: Ad","kind":"variable"},{"line":20,"col":48,"len":13,"label":"ad_archive_id: str","kind":"field"},{"line":21,"col":14,"len":6,"label":"detail: Ad","kind":"variable"},{"line":21,"col":32,"len":6,"label":"detail: Ad","kind":"variable"},{"line":21,"col":46,"len":6,"label":"detail: Ad","kind":"variable"},{"line":23,"col":40,"len":16,"label":"fec_committee_id: Optional[str]","kind":"field"},{"line":23,"col":80,"len":7,"label":"address: Optional[str]","kind":"field"},{"line":11,"col":52,"len":6,"label":"AdType — enum: ALL, CREDIT, EMPLOYMENT, HOUSING, POLITICAL_AND_ISSUE","kind":"enum"},{"line":13,"col":31,"len":9,"label":"first_hit: Ad","kind":"variable"},{"line":20,"col":38,"len":9,"label":"first_hit: Ad","kind":"variable"},{"line":23,"col":25,"len":14,"label":"funding_entity: Optional[FundingEntity]","kind":"field"},{"line":23,"col":65,"len":14,"label":"funding_entity: Optional[FundingEntity]","kind":"field"},{"line":23,"col":18,"len":6,"label":"detail: Ad","kind":"variable"},{"line":23,"col":58,"len":6,"label":"detail: Ad","kind":"variable"},{"line":25,"col":29,"len":3,"label":"exc: AdNotFound","kind":"variable"}]},"sdk_delivery_state":"available","summary":"Search and retrieve ads from Meta's Ad Library across Facebook, Instagram, Messenger, and Audience Network. Supports keyword search, page-specific ad listing, and individual ad lookup with full creative details, spend data, and political ad transparency information.","updated_at":"2026-09-07T08:24:06.03012+00:00","user_variants":[],"latest_version":4,"user_status":null,"user_scraper_id":null,"contributes_to_marketplace":true,"pinned_version":null,"seo_content":{"faqs":[{"a":"Yes. Meta provides an official Ad Library API at https://www.facebook.com/ads/library/api/ — it requires a Facebook developer account and approved access. The Parse API covers the same public Ad Library data without requiring Meta developer credentials.","q":"Does Meta have an official developer API for the Ad Library?"},{"a":"No. Spend ranges and impression counts are only populated for political and issue ads, which Meta is required to disclose publicly. For standard commercial ads, the `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.","q":"Does `search_ads` return spend data for all ads?"},{"a":"Not currently. The endpoints return creative fields (images, videos, captions, CTA), spend ranges for political ads, and page/funding entity information. Audience targeting breakdowns are not included in the current response schema. You can fork this API on Parse and revise it to add an endpoint that surfaces targeting data where Meta makes it publicly available.","q":"Does the API return audience targeting details — age, gender, or geographic targeting used for a specific ad?"},{"a":"All three endpoints return a `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.","q":"How does pagination work across endpoints?"},{"a":"The `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.","q":"Is Ad Library data available for all countries?"}],"keywords":["facebook ad library API","meta ads transparency API","political ad spend data API","facebook ads keyword search API","instagram ad creative data","meta ad library scraper API","facebook page ads lookup","ad library funding entity disclosure","facebook ad impressions data API","political issue ads spend range API","meta ad library competitor research","facebook ad ID lookup API","ad library country filter API","facebook ad creative images API"],"use_cases":["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_ads` with `ad_type=political_and_issue_ads` to surface spend ranges and funding disclosures","Build an ad creative library by collecting images, videos, captions, and CTA text from `search_ads` results","Audit a specific ad by ID using `get_ad_details` to retrieve its full creative content, link URL, and impression data","Research advertiser activity in a specific country by passing a `country` code to any endpoint","Detect new ad launches for a brand by polling `search_page_ads` with `active_status=active` for a given page ID","Analyze media format trends by filtering `search_ads` with the `media_type` parameter across a keyword set"],"meta_title":"Facebook Ad Library API – Meta Ads Data","generated_at":"2026-06-24T18:17:33.925148+00:00","lead_paragraph":"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.","schema_version":2,"meta_description":"Search and retrieve Meta Ad Library data across Facebook, Instagram, and Messenger. Get ad creatives, spend ranges, impressions, and political transparency info.","primary_category":"social_media","long_description_md":"## What the API Covers\n\nThe 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.\n\n## Endpoints and Parameters\n\n`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`.\n\n## Coverage and Limitations\n\nSpend 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.","generated_with_model":"global.anthropic.claude-sonnet-4-6","secondary_categories":["government_public","b2b_directory"]},"primary_category":"social_media","secondary_categories":["government_public","b2b_directory"],"access_requirements":[]}