Facebook Ad Library API
Search public Facebook ads by keyword, find advertiser Pages, collect ads for a Page ID, or retrieve one known ad with normalized creative, media, delivery, CTA, and destination fields.
Available Facebook Ad Library APIs
Use Search for keyword-based ad discovery, Company Search to find a Page ID, Company Ads to collect ads from that Page, or Ad Details to retrieve one known public ad.
What Facebook Ad Library data can you retrieve?
SocQ returns normalized public ad and advertiser records for creative research, competitor monitoring, campaign analysis, and advertising datasets.
Ad search results
Search public ads by keyword or exact phrase, with optional country, status, media, ad type, date, sort, and result-limit filters.
Advertiser Page records
Find Page IDs, names, URLs, categories, countries, images, verification values, visible Page likes, and linked Instagram context.
Page-specific ad collections
Collect a bounded set of unique public ads for one numeric advertiser Page ID with optional delivery and media filters.
Creative text and media
Retrieve available ad titles, body text, link descriptions, display formats, and deduplicated public image or video references.
Delivery and market context
Keep available start and end times, active status, publisher platforms, countries, reach, currency, spend, and Page-like signals.
Calls to action and destinations
Retrieve visible CTA text and type, public destination URLs, Ad Library URLs, advertiser identity, and collection timestamps when exposed.
SocQ vs Meta Ad Library API
SocQ provides ready-to-use public ad collection workflows. Meta's Ad Library API is the official choice for direct access to Meta's ad transparency archive.
| Capability | SocQ | Meta Ad Library API |
|---|---|---|
| Primary use | Search public ads and collect advertiser or ad details | Query Meta's official ad transparency archive |
| Authentication | SocQ API key; no customer Facebook OAuth | Meta app, access token and Ad Library access |
| Starting input | Keyword, company name, Page ID or public Ad Library URL | Official archive query parameters and Meta identifiers |
| Create or manage ads | Not supported | Not supported; use Meta Marketing API |
| Response format | Normalized SocQ records | Native Meta Graph API objects |
How the Facebook Ad Library API works
All four APIs use the same asynchronous task and paginated result workflow.
1. Choose the API and input
Start with a keyword, company name, numeric Page ID, or public /ads/library URL, depending on the record you need.
2. Submit and track the task
Send the matching POST request, save the returned task_id, and poll /v1/tasks/{task_id} until processing finishes.
3. Read the normalized results
Process data.results.items and follow next_cursor while has_more is true.
Authenticate with your SocQ API key and submit a keyword to the Search endpoint. The other Ad Library APIs use the same task flow.
curl -X POST "https://api.socq.ai/v1/facebook-ad-library/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"running shoes","results_limit":100,"status":"ACTIVE"}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueCommon Facebook Ad Library API use cases
Competitor ad monitoring
Track public ads from selected advertiser Pages and compare creative, media, delivery status, markets, CTAs, and destinations over time.
Creative and messaging research
Search product, category, or brand terms to review public ad copy, formats, media, calls to action, and landing-page destinations.
Advertiser discovery
Resolve company or brand names into public Page IDs and identity fields before collecting a focused Page-specific ad set.
Advertising datasets
Store normalized ad IDs, advertiser records, creative fields, delivery context, source URLs, and collected_at timestamps for analysis.
Limits and public-data policy
Facebook Ad Library results are point-in-time public records. These APIs do not manage ad accounts or provide private campaign performance data.
- Search requires one non-empty query; results_limit defaults to 100 and accepts integers from 20 through 2,000.
- Company Search accepts one company or Page-name query, does not accept results_limit, and can return several similarly named Page candidates.
- Company Ads requires one numeric Page ID; results_limit accepts 20 through 2,000 and filters can reduce the returned record count.
- Ad Details accepts one public facebook.com/ads/library URL with a numeric id and returns at most one normalized ad record.
- A completed task can return no records when an ad, Page, or filtered result set is unavailable in the public source.
- Reach, spend, currency, media, dates, CTA, destination, and advertiser fields can be absent and must not be interpreted as zero.
Facebook Ad Library API frequently asked questions
What is the Facebook Ad Library API?
The Facebook Ad Library API is a set of SocQ endpoints for searching public ads, finding advertiser Pages, collecting Page-specific ads, and retrieving details for known public ads.
Which Facebook Ad Library API should I use?
Use Search for keyword discovery, Company Search to find a Page ID, Company Ads to collect ads for that ID, and Ad Details for one known public Ad Library URL.
What can I search and filter?
Search accepts a keyword or exact phrase plus optional country, status, media, ad-type, date, sort, and result-limit filters. Company Ads supports Page-specific delivery and media filters.
What public ad data is returned?
Results can include ad and advertiser identity, creative text, images or videos, delivery dates, active status, publisher platforms, countries, CTA, destination, and visible public signals.
Why can a completed request return no results?
The public source may have no match for the submitted input, filters may exclude all records, or the requested ad or Page may no longer be publicly available.
Is this the same as the Facebook social data or Marketplace API?
No. Facebook Ad Library endpoints are separate from SocQ's Facebook Page, post, and comment APIs and from its Facebook Marketplace listing APIs.
How are Facebook Ad Library results priced?
Search ads, Company Search candidates, and Company Ads records cost 0.5 credits per returned result. Ad Details costs 0.6 credits per returned result, and empty results have no result charge.