Facebook Ad Library Company Ads
Facebook Ad Library company ads are public advertiser records with creative text, media, Page identity, delivery dates, active state, publisher platforms, country context, and visible signals. These records support advertiser monitoring, creative comparison, market-specific review, and collection-time reporting.
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
| Parameters | Required | Description |
|---|---|---|
page_id | Required | Required numeric Facebook Ad Library advertiser Page ID. Use Company Search first when the Page ID is unknown; one task accepts one Page ID. |
results_limit | Optional | Maximum number of unique ads to save. The default is 100 and accepted values are integers from 20 through 2,000. |
country | Optional | Use ALL or one two-letter country code. The default is ALL. |
status | Optional | Ad delivery status filter. Use exactly ALL, ACTIVE, or INACTIVE; the default is ACTIVE. |
media_type | Optional | Creative media filter. Use exactly ALL, IMAGE, VIDEO, MEME, IMAGE_AND_MEME, or NONE; the default is ALL. |
language | Optional | Optional two-letter ad language code. |
sort_by | Optional | Sort returned ads by total_impressions or relevancy_monthly_grouped; the default is total_impressions. |
start_date | Optional | Optional start date in YYYY-MM-DD format. It cannot be later than end_date. |
end_date | Optional | Optional end date in YYYY-MM-DD format. It cannot be earlier than start_date. |
How to Use
Submit one advertiser Page ID with optional filters, track the asynchronous task, and read normalized ad records with cursor pagination.
- Obtain the numeric advertiser Page ID and choose any country, status, media, language, sort, or date filters.
- Submit page_id and the selected filters to /v1/facebook-ad-library/company-ads, then capture task_id.
- Poll /v1/tasks/{task_id} until processing succeeds or returns a failure.
- 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 trueBest 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
Use these APIs when you need a different type of public Facebook Ad Library data.
- Facebook Ad Library Search API — Search public ads by keyword with match, ad, country, status, media, sort, date, and result-limit controls.
- 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 Ad API — Collect one public Ad Library ad from its URL with creative, advertiser, media, delivery, CTA, and visible signal fields.