Facebook Ad Library Search
Facebook Ad Library Search results are public ads matched to a keyword, with advertiser Page identity, creative text and media, delivery dates, publisher platforms, countries, and visible metrics. These records support creative discovery, advertiser research, active-ad monitoring, and comparison across repeatable queries.
Features
- Keyword and phrase matchingSearch with one non-empty query and choose unordered keyword matching or exact-phrase matching to control how public ads qualify.
- Search filters and orderingNarrow results by ad type, country, delivery status, media type, date range, and supported impression or relevance ordering.
- Normalized ad and advertiser recordsReturn ad archive identity, public source URL, advertiser Page context, creative title, body text, and collection time in a consistent record.
- Creative, delivery, and public contextKeep available images or videos, start and end times, active state, publisher platforms, countries, CTA details, destinations, and visible metrics.
- Bounded deduplicated collectionRequest 20 through 2,000 results while duplicate archive IDs or public ad URLs are saved once across available result pages.
Parameters
| Parameters | Required | Description |
|---|---|---|
query | Required | Required non-empty keyword or phrase used to search public ads. |
results_limit | Optional | Maximum unique ads to save. Defaults to 100 and accepts integers from 20 through 2,000. |
sort_by | Optional | Result ordering. Defaults to total_impressions and also supports relevancy_monthly_grouped. |
search_type | Optional | Keyword matching mode. Defaults to keyword_unordered; use keyword_exact_phrase when word order must match. |
ad_type | Optional | Ad category filter. Defaults to all and can be restricted to political_and_issue_ads. |
country | Optional | Country filter. Use ALL or a two-letter country code; submitted letter codes are normalized to uppercase. |
status | Optional | Delivery-status filter. Defaults to ACTIVE and supports ALL, ACTIVE, or INACTIVE. |
media_type | Optional | Creative media filter. Supports ALL, IMAGE, VIDEO, MEME, IMAGE_AND_MEME, or NONE and defaults to ALL. |
start_date | Optional | Optional impression-period start date in YYYY-MM-DD format. |
end_date | Optional | Optional impression-period end date in YYYY-MM-DD format; it cannot precede start_date. |
How to Use
Submit a keyword with the filters that define your ad sample, then read every normalized record from the completed asynchronous task.
- Prepare one non-empty query and choose optional matching, ad, country, status, media, sort, date, and result-limit controls.
- POST the request to /v1/facebook-ad-library/search and store the returned task_id.
- Poll /v1/tasks/{task_id} until the task succeeds or returns a failure.
- Read data.results.items, then follow next_cursor while has_more remains true.
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,"country":"US","status":"ACTIVE","media_type":"VIDEO","search_type":"keyword_unordered"}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueBest Use Cases
- Keyword-led ad discovery: Use the submitted query, ad IDs, creative text, advertiser names, and public URLs to assemble a traceable set of matching public ads.
- Creative and format comparison: Compare creative titles, body text, images, videos, display formats, CTA values, destinations, and publisher platforms across matched records.
- Active-ad monitoring: Repeat a defined query and compare ad IDs, active state, start and end times, publisher platforms, and collection times across observations.
- Advertiser candidate research: Use advertiser Page IDs, names, aliases, URLs, visible Page likes, and the matching creative to identify Pages for focused follow-up research.
Pro Tips
- Use keyword_exact_phrase when word order carries meaning; use keyword_unordered when ads may vary the phrase order.
- Apply country, status, media, ad-type, and date filters before increasing results_limit so the saved sample remains focused.
- Treat results_limit as the collection ceiling, then follow task-result cursors until has_more is false to read every stored record.
- Deduplicate repeated runs by ad archive ID or public ad URL while retaining extra.search_query and collected_at for observation context.
- Treat missing reach, spend, Page likes, end dates, media, CTA, or country values as unavailable public data rather than zero.
Related APIs
Use these APIs when you need a different type of public Facebook Ad Library data.
- Facebook Ad Library Company Search API — Find advertiser Page candidates by company or Page name with Page IDs, classifications, images, visible audience, and linked Instagram signals.
- Facebook Ad Library Company Ads API — Collect public ads for one advertiser Page ID with creative, delivery, market, media, CTA, and visible signal fields.
- Facebook Ad Library Ad API — Collect one public Ad Library ad from its URL with creative, advertiser, media, delivery, CTA, and visible signal fields.
Combine Facebook Ad Library data with public data from other supported social platforms.