How-to guide
How to search the Facebook Ad Library for a competitor's ads
Send a keyword to facebook/adlibrary/search/ads and it returns Ad Library ads matching it across all advertisers, each with creative text, images, the sponsoring page and its running status. The results are structured, so you can filter and store them instead of scrolling the library by hand. A run costs 5 credits.
5 credits per run, in one API call
The calls, in order
Each step is one request to the SocialCrawl API. Copy the curl, add your key and run it.
Search Facebook Ad Library
5 credits per callTry this call on its endpoint page: Search Facebook Ad Librarycurlcurl -H "x-api-key: YOUR_API_KEY" \ "https://www.socialcrawl.dev/v1/facebook/adlibrary/search/ads?query=artificial+intelligence"
What comes back
A real response from facebook/adlibrary/search/ads, captured from the SocialCrawl API, with long lists cut to two rows.
JSON
{
"success": true,
"platform": "facebook",
"endpoint": "/v1/facebook/adlibrary/search/ads",
"data": {
"items": [
{
"ad_archive_id": "2139784727416787",
"collation_count": 3,
"collation_id": "3161863597339791",
"is_active": true,
"page_id": "576808235525866",
"page_is_deleted": false,
"snapshot": {
"branded_content": {
"page_id": "576808235525866",
"page_is_deleted": false,
"page_profile_uri": "https://www.facebook.com/user_b67ec1/",
"page_name": "I-Hub IIT Patna Artificial Intelligence and Machine Learning"
},
"page_id": "101904016202906",
"page_is_deleted": false,
"page_profile_uri": "https://www.facebook.com/user_7f99b8/",
"root_reshared_post": null,
"byline": null,
"disclaimer_label": null,
"page_name": "High Onn Knowledge",
"page_profile_picture_url": "https://scontent-lga3-3.xx.fbcdn.net/v/t39.35426-6/758964133_1751982689261468_2817971388824079048_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=108&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=9GujPrrsoVoQ7kNvwEzBKw3&_nc_oc=AdphdY9dc8BQzCqP4mwtaAr9SYtMfm7zoH66zN4yKfWBTNvc7pVmu_ixehEQFS7kOTQ&_nc_zt=14&_nc_ht=scontent-lga3-3.xx&_nc_gid=vwQxxKvZ9al3_XJcdevFCw&_nc_ss=78289&oh=00_AQM3MSOEkGzujevG2xnS1u5nuBIK87OELHdeRMTdSkZp8Q&oe=6AC52A91",
"event": null,
"caption": "www.masaischool.com",
"cta_text": "Apply now",
"cards": [],
"body": {
"text": "Build strong fundamentals with the AI & Machine Learning Certification Program by Vishlesan i-Hub, IIT Patna. Learn core AI & ML concepts through hands-on projects and practical learning. \n\nClick the link to Apply Now or get the link from my bio"
},
"cta_type": "APPLY_NOW",
"display_format": "VIDEO",
"link_description": null,
"link_url": "https://www.masaischool.com/program/iit-patna/ai-ml-sop/accelerate",
"images": [],
"page_categories": [
"Education website",
"Education Service"
],
"page_like_count": 86,
"title": null,
"videos": [
{
"video_hd_url": "https://video-lga3-1.xx.fbcdn.net/o1/v/t2/f2/m367/AQMlTgbEWk1bFuhd7FdLhLSeESnhUJiyb9306-Ph3kJgVsqb4LrlWnRv3M1H--g2ymC57qD3k-b3VQIbA2ymTHZziJltjmZ3N1iCFTZBPA.mp4?_nc_cat=111&_nc_sid=ef5aa3&_nc_ht=video-lga3-1.xx.fbcdn.net&_nc_ohc=rjpPzmru7qQQ7kNvwHPotPn&efg=eyJ2ZW5jb2RlX3RhZyI6Inhwdl9wcm9ncmVzc2l2ZS5WSV9VU0VDQVNFX1BST0RVQ1RfVFlQRS4uQzMuNzIwLnByb2dyZXNzaXZlX2gyNjQtYmFzaWMtZ2VuMl83MjBwIiwieHB2X2Fzc2V0X2lkIjoxMDAxMzMzNjUyMzU1MTg4LCJhc3NldF9hZ2VfZGF5cyI6MTI2LCJ2aV91c2VjYXNlX2lkIjoxMjM3NCwiZHVyYXRpb25fcyI6MjgsInVybGdlbl9zb3VyY2UiOiJ3d3cifQ%3D%3D&ccb=17-1&_nc_gid=vwQxxKvZ9al3_XJcdevFCw&_nc_ss=78289&_nc_zt=28&oh=00_AQPFDX9kfbHW6J7II7JEruZ2Tv5INiZJA7KyLg7oAIhF8A&oe=6AC530BF",
"video_preview_image_url": "https://example.com/redacted",
"video_sd_url": "https://video-lga3-3.xx.fbcdn.net/o1/v/t2/f2/m367/AQOQDi6sUF-QKcYNA2M09_I4Em9Ctdb77on_XXtDkEpFLuqMsjuaP0EkDL7dmYUzYBPNRc_Usk93gUHzqrCB-KdMw2GPRu61sB7LXagv2A.mp4?_nc_cat=104&_nc_sid=ef5aa3&_nc_ht=video-lga3-3.xx.fbcdn.net&_nc_ohc=hm5I4CqeRrwQ7kNvwHpkIDT&efg=eyJ2ZW5jb2RlX3RhZyI6Inhwdl9wcm9ncmVzc2l2ZS5WSV9VU0VDQVNFX1BST0RVQ1RfVFlQRS4uQzMuMzYwLnByb2dyZXNzaXZlX2gyNjQtYmFzaWMtZ2VuMl8zNjBwIiwieHB2X2Fzc2V0X2lkIjoxMDAxMzMzNjUyMzU1MTg4LCJhc3NldF9hZ2VfZGF5cyI6MTI2LCJ2aV91c2VjYXNlX2lkIjoxMjM3NCwiZHVyYXRpb25fcyI6MjgsInVybGdlbl9zb3VyY2UiOiJ3d3cifQ%3D%3D&ccb=17-1&_nc_gid=vwQxxKvZ9al3_XJcdevFCw&_nc_ss=78289&_nc_zt=28&oh=00_AQM0pS8xVx5ZI8zvZng5xRvDMkag2tG22ylsyVpw6HZKoQ&oe=6AC521AA",
"watermarked_video_hd_url": null,
"watermarked_video_sd_url": null
}
],
"is_reshared": false,
"extra_links": [],
"extra_texts": [],
"extra_images": [],
"extra_videos": [],
"country_iso_code": null,
"brazil_tax_id": null,
"additional_info": null,
"ec_certificates": []
},
"has_user_reported": false,
"report_count": null,
"menu_items": [],
"state_media_run_label": null,
"page_name": "I-Hub IIT Patna Artificial Intelligence and Machine Learning",
"impressions_with_index": {
"impressions_text": null,
"impressions_index": -1
},
"gated_type": "ELIGIBLE",
"categories": [
"UNKNOWN"
],
"is_aaa_eligible": false,
"contains_digital_created_media": false,
"reach_estimate": null,
"currency": "",
"spend": null,
"end_date": 1790838000,
"publisher_platform": [
"FACEBOOK",
"INSTAGRAM"
],
"start_date": 1785308400,
"contains_sensitive_content": false,
"total_active_time": null,
"regional_regulation_data": {
"finserv": {
"is_deemed_finserv": false,
"is_limited_delivery": false
},
"tw_anti_scam": {
"is_limited_delivery": false
}
},
"hide_data_status": "NONE",
"fev_info": null,
"ad_id": null,
"targeted_or_reached_countries": [],
"url": "https://www.facebook.com/ads/library?id=2139784727416787",
"start_date_string": "2026-07-29T07:00:00.000Z",
"end_date_string": "2026-10-01T07:00:00.000Z"
},
{
"ad_archive_id": "1055669670399239",
"collation_count": 2,
"collation_id": "1383170080575251",
"is_active": true,
"page_id": "195942257089305",
"page_is_deleted": false,
"snapshot": {
"branded_content": null,
"page_id": "195942257089305",
"page_is_deleted": false,
"page_profile_uri": "https://www.facebook.com/user_8757b4/",
"root_reshared_post": null,
"byline": null,
"disclaimer_label": null,
"page_name": "TalentSprint, Part of Accenture",
"page_profile_picture_url": "https://scontent-lga3-2.xx.fbcdn.net/v/t39.35426-6/772725939_1960945541196934_8779058005522953830_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=100&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=ttZg0x2EDHwQ7kNvwGERQrn&_nc_oc=AdptUunFqum9jGJ7Q_kOWLhBOQedUL63_LOklzd3dL6SyaERC2gsYl1FOGGz06bxpCc&_nc_zt=14&_nc_ht=scontent-lga3-2.xx&_nc_gid=vwQxxKvZ9al3_XJcdevFCw&_nc_ss=78289&oh=00_AQMOGaKL0SNA1ZoLLKyL00DcLdTMxHtrmQFmv52w0prGuQ&oe=6AC516BE",
"event": null,
"caption": "galgotiasuniversity.edu.in",
"cta_text": "Learn more",
"cards": [
{
"body": "Looking for a BTech program that goes beyond classroom learning?\n\nIndustry-integrated curriculum, practical projects, future technologies, and career-focused learning designed for tomorrow's engineers.",
"cta_type": "LEARN_MORE",
"caption": "",
"link_description": "Learn beyond the classroom with industry-integrated engineering education.",
"link_url": "https://www.galgotiasuniversity.edu.in/industry-integrated-degrees/btech.php?utm_source=fb_webconv&utm_medium=paid_facebook&utm_campaign=gu-fb_webconv-performance-audience-btech-parents&utm_content=gu-fb_webconv-performance-audience-btech-parents",
"title": "👉 Not Just a BTech. Build the Future with AI.",
"cta_text": "Learn More",
"video_hd_url": null,
"video_preview_image_url": null,
"video_sd_url": null,
"watermarked_video_hd_url": null,
"watermarked_video_sd_url": null,
"image_crops": [],
"original_image_url": "https://scontent-lga3-1.xx.fbcdn.net/v/t39.35426-6/772966218_1727642645168960_3218337231393249146_n.jpg?_nc_cat=103&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=5pduJyWHO9QQ7kNvwFsA7sI&_nc_oc=AdpblkfHPX4ONlhj9nimo7AV7aAHCAUU5Ypbs1sFTzyKNBXld0Lve8MX7F2Sx7RdyEA&_nc_zt=14&_nc_ht=scontent-lga3-1.xx&_nc_gid=vwQxxKvZ9al3_XJcdevFCw&_nc_ss=78289&oh=00_AQNak9nfOzxnRTOQUKyhazs--urUcznD8wVwDLDdNBUp5A&oe=6AC52018",
"resized_image_url": "https://scontent-lga3-3.xx.fbcdn.net/v/t39.35426-6/772510818_897126909711802_599938382479698218_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=102&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=Ro-KszK899gQ7kNvwGCAB-U&_nc_oc=Adrw5x5arI_dKADNpSWIi4WLL-5LmDZW6Z93KaBbioFph-hXiJaCvh1zh8PYKR9X1o4&_nc_zt=14&_nc_ht=scontent-lga3-3.xx&_nc_gid=vwQxxKvZ9al3_XJcdevFCw&_nc_ss=78289&oh=00_AQPXv35Au7VXFesb42_tkwWVXlmaJYF2Wowbs_ltEhSJ8Q&oe=6AC54AF5",
"watermarked_resized_image_url": ""
},
{
"body": "Looking for a BTech program that goes beyond classroom learning?\n\nIndustry-integrated curriculum, practical projects, future technologies, and career-focused learning designed for tomorrow's engineers.",
"cta_type": "LEARN_MORE",
"caption": "",
"link_description": "Learn beyond the classroom with industry-integrated engineering education.",
"link_url": "https://www.galgotiasuniversity.edu.in/industry-integrated-degrees/btech.php?utm_source=fb_webconv&utm_medium=paid_facebook&utm_campaign=gu-fb_webconv-performance-audience-btech-parents&utm_content=gu-fb_webconv-performance-audience-btech-parents",
"title": "👉 Not Just a BTech. Build the Future with AI.",
"cta_text": "Learn More",
"video_hd_url": null,
"video_preview_image_url": null,
"video_sd_url": null,
"watermarked_video_hd_url": null,
"watermarked_video_sd_url": null,
"image_crops": [],
"original_image_url": "https://scontent-lga3-2.xx.fbcdn.net/v/t39.35426-6/772138377_1065149695960474_8145393550861927560_n.jpg?_nc_cat=100&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=WOhY7jjORzsQ7kNvwG-eeUZ&_nc_oc=Adr7JA-3d55aUp0_mQq_zvcHx474KgDCnxnKKvytdRv7ezuRdKdrG2HsjmESVC_uAuM&_nc_zt=14&_nc_ht=scontent-lga3-2.xx&_nc_gid=vwQxxKvZ9al3_XJcdevFCw&_nc_ss=78289&oh=00_AQNnBFKyCEE9sABg_r1anoD4DCqTeWqK8YxXbrzJNJuogw&oe=6AC5175B",
"resized_image_url": "https://scontent-lga3-1.xx.fbcdn.net/v/t39.35426-6/772965523_1807113250741448_8419369904608238412_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=109&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=U_-wQB52yMgQ7kNvwG3XfFY&_nc_oc=Ado7NTrzxf9OByha-2xj8GRU5pf40xkOp7VoPYNT4RndkB-Yzh6aoYxZ7bGYuxv2imk&_nc_zt=14&_nc_ht=scontent-lga3-1.xx&_nc_gid=vwQxxKvZ9al3_XJcdevFCw&_nc_ss=78289&oh=00_AQP4Xx_HPel4VXyrhYTRLyRcU3uQwoBeM3szNlgAKrSPyA&oe=6AC54169",
"watermarked_resized_image_url": ""
}
],
"body": {
"text": "Looking for a BTech program that goes beyond classroom learning?\n\nIndustry-integrated curriculum, practical projects, future technologies, and career-focused learning designed for tomorrow's engineers."
},
"cta_type": "LEARN_MORE",
"display_format": "DCO",
"link_description": "Learn beyond the classroom with industry-integrated engineering education.",
"link_url": "https://www.galgotiasuniversity.edu.in/industry-integrated-degrees/btech.php?utm_source=fb_webconv&utm_medium=paid_facebook&utm_campaign=gu-fb_webconv-performance-audience-btech-parents&utm_content=gu-fb_webconv-performance-audience-btech-parents",
"images": [],
"page_categories": [
"Education"
],
"page_like_count": 639637,
"title": "👉 Not Just a BTech. Build the Future with AI.",
"videos": [],
"is_reshared": false,
"extra_links": [],
"extra_texts": [],
"extra_images": [],
"extra_videos": [],
"country_iso_code": null,
"brazil_tax_id": null,
"additional_info": null,
"ec_certificates": []
},
"has_user_reported": false,
"report_count": null,
"menu_items": [],
"state_media_run_label": null,
"page_name": "TalentSprint, Part of Accenture",
"impressions_with_index": {
"impressions_text": null,
"impressions_index": -1
},
"gated_type": "ELIGIBLE",
"categories": [
"UNKNOWN"
],
"is_aaa_eligible": false,
"contains_digital_created_media": false,
"reach_estimate": null,
"currency": "",
"spend": null,
"end_date": 1790838000,
"publisher_platform": [
"FACEBOOK",
"INSTAGRAM"
],
"start_date": 1786518000,
"contains_sensitive_content": false,
"total_active_time": null,
"regional_regulation_data": {
"finserv": {
"is_deemed_finserv": false,
"is_limited_delivery": false
},
"tw_anti_scam": {
"is_limited_delivery": false
}
},
"hide_data_status": "NONE",
"fev_info": null,
"ad_id": null,
"targeted_or_reached_countries": [],
"url": "https://www.facebook.com/ads/library?id=1055669670399239",
"start_date_string": "2026-08-12T07:00:00.000Z",
"end_date_string": "2026-10-01T07:00:00.000Z"
}
],
"next_cursor": "AQHT9bZGmT9QXCGQ5tqS-kL80Awg3MUVy8aPKjLViaCFbDdFyJh34pKRBMcXAOokd9Hv",
"dropped": 0
},
"credits_used": 5,
"request_id": "req_example000000",
"cached": false,
"pagination": {
"next_cursor": "sc.eyJ2IjoyLCJjIjoiQVFIVDliWkdtVDlRWENHUTV0cVMta0w4MEF3ZzNNVVZ5OGFQS2pMVmlhQ0ZiRGRGeUpoMzRwS1JCTWNYQU9va2Q5SHYiLCJlIjoiZmFjZWJvb2svYWRsaWJyYXJ5L3NlYXJjaC9hZHMiLCJwIjoiY3Vyc29yIn0",
"has_more": true,
"page_size": 29
},
"credits_remaining": 9999,
"source": "captured",
"captured_at": "2026-10-02T07:32:32.822Z",
"redacted": true
}Hand this job to your coding agent
Paste this prompt into Claude Code, Cursor or any agent that can make HTTP requests. It names every endpoint and parameter the job needs.
Prompt
Use the SocialCrawl API for this job: List the ads a company is running, from the public ad library.
Base URL: https://www.socialcrawl.dev. Send the API key in the x-api-key header (an Authorization: Bearer header also works). Values in braces are placeholders to fill.
1. GET /v1/facebook/adlibrary/search/ads?query=artificial%20intelligence
Every response is JSON with data, credits_used and request_id. The full endpoint reference is at https://www.socialcrawl.dev/llms.txt.FAQ
Have a question? We got answers
Find answers to frequently asked questions about SocialCrawl's API, pricing, and capabilities.
Contact usWhat does each ad include?
Each ad has the creative text, images or video, the call to action, the page name and id of the sponsor, a running status and an ad archive id. Impression text appears when the library provides it.
Can I look up one advertiser instead of a keyword?
Yes. The registry says that if you already know the advertiser, adlibrary/company/ads is more direct than a keyword search, which is better suited to finding ads across all advertisers.
How do I see whether an ad is still running?
Each ad carries an is_active flag. Filter on it to keep only live ads, which are the ones a competitor is currently paying for.
How do I page through more ads?
Pass the next_cursor from the response into the next request. The cursor continues the same keyword search, so keep the query identical while you page.
Does it work for other ad libraries?
This endpoint covers the Facebook Ad Library. The registry lists separate ad library endpoints under other platform names, such as TikTok, so check the platform's endpoint list for a match.
How much does one run cost?
One run of the example above costs 5 credits across one API call. Every new account gets 100 free credits, credits for failed or empty calls are refunded automatically, and there is no subscription.
Ask AI about SocialCrawl