Facebook Ad Library Company Ads API

Facebook Ad Library Company Ads

Features

• Advertiser Page-scoped collectionUse one numeric advertiser Page ID to keep every returned ad associated with the selected public Page rather than a keyword search.
• Market and delivery filtersNarrow collection by country, delivery status, media type, language, date range, and supported sort order before records are saved.
• Creative, media, and destination fieldsReturn available titles, body text, images or videos, CTA values, public destination URLs, and display formats for each ad.
• Advertiser and delivery contextKeep Page identity, Page likes, delivery dates, active state, publisher platforms, countries, reach, currency, and spend when publicly exposed.
• Bounded unique ad recordsFollow available source pages, remove duplicate archive IDs or URLs, and stop at results_limit or the last available page.

Parameters

How to Use

Submit one advertiser Page ID with optional filters, track the asynchronous task, and read normalized ad records with cursor pagination.

1. Obtain the numeric advertiser Page ID and choose any country, status, media, language, sort, or date filters.
2. Submit page_id and the selected filters to /v1/facebook-ad-library/company-ads, then capture task_id.
3. Poll /v1/tasks/{task_id} until processing succeeds or returns a failure.
4. Read data.results.items, then request the next page with next_cursor while has_more is true.

curl -X POST "https://api.socq.ai/v1/facebook-ad-library/company-ads" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page_id":"51212153078","results_limit":100,"country":"US","status":"ACTIVE","media_type":"ALL"}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Best Use Cases

• Advertiser ad monitoring: Track archive IDs, creative text, media, active state, delivery dates, source URLs, and collected_at for a known advertiser Page.
• Creative and format comparison: Compare text, images or videos, display format, CTA, destination links, and collation context across the Page's returned ads.
• Market-filtered ad review: Run country, language, status, media, and date filters to build separate ad sets for defined market or delivery questions.
• Public signal snapshot reporting: Combine Page identity, Page likes, reach, spend, currency, delivery state, and collected_at when those public values are exposed.

Pro Tips

• Start with country set to ALL and broad media and date filters, then narrow one condition at a time so an empty result can be interpreted correctly.
• Use the minimum results_limit of 20 while validating a Page ID and filter set, then increase it only when the returned scope matches the task.
• Submit separate tasks for brands with multiple advertiser Page IDs because one Company Ads request accepts one Page ID.
• Deduplicate repeated runs by ad id, treat missing reach, spend, media, and dates as unavailable rather than zero, and use collation fields for grouping instead of performance claims.

Related APIs