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. |
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. |
sort_by | Optional | Result ordering. Defaults to total_impressions and also supports relevancy_monthly_grouped. |
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.