Facebook Ad Library Ad
Facebook Ad Library ads are public advertising records with creative text, advertiser identity, media, calls to action, delivery timing, active status, and available reach or spend signals. These fields support selected-ad enrichment, creative review, public delivery monitoring, and point-in-time comparison.
Features
- Direct Ad Library URL resolutionResolve one public /ads/library URL with a numeric id query parameter into at most one normalized ad record.
- Creative and advertiser contextReturn the ad archive ID, creative title and text, advertiser Page identity, public Page URL, call to action, and destination link when exposed.
- Delivery and visible signalsPreserve start and end times, active status, publisher platforms, country context, Page likes, reach, currency, and spend when the public record provides them.
- Normalized multi-card mediaSelect available snapshot or first-card text for the standard fields and deduplicate image and video assets found across the snapshot and cards without presenting a complete variant table.
Parameters
| Parameters | Required | Description |
|---|---|---|
url | Required | Required public Facebook Ad Library ad URL. Use the canonical https://www.facebook.com/ads/library/?id={numeric_id} form; one request accepts one URL. |
How to Use
Submit one public Ad Library URL, track the asynchronous task, and read the normalized ad record from the standard result envelope.
- Prepare one public Facebook Ad Library URL whose path is /ads/library and whose query contains a numeric id.
- Submit url to /v1/facebook-ad-library/ad and capture the returned task_id.
- Poll /v1/tasks/{task_id} until the task succeeds or returns a failure.
- Read data.results.items; this endpoint returns at most one record, so next_cursor normally remains null and has_more remains false.
curl -X POST "https://api.socq.ai/v1/facebook-ad-library/ad" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://www.facebook.com/ads/library/?id=702369045530963"}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items; this operation returns at most one itemBest Use Cases
- Enrich a selected ad: Use the archive ID, advertiser identity, creative title, body text, media, CTA, destination URL, and input URL to complete an existing ad record.
- Review creative assets and destinations: Inspect deduplicated image or video references together with display format, CTA text, CTA type, and the public destination link for a known ad.
- Review public delivery context: Use active status, start and end times, publisher platforms, country values, and available reach or spend fields to examine the public delivery context.
- Preserve point-in-time ad snapshots: Store creative, advertiser, delivery, visible signal, input URL, and collected_at fields for later comparison of the same known ad.
Pro Tips
- Submit an Ad Library URL with the exact /ads/library path and a numeric id query parameter; Page URLs, Page IDs, post URLs, and raw ad IDs are not accepted inputs.
- Treat a succeeded task with no record as a valid unavailable or not-found outcome when the submitted URL is syntactically valid.
- Handle reach, spend, Page likes, media, end_at, advertiser profile URL, CTA, and country values as optional public fields instead of converting missing values to zero.
- For ads with multiple cards or creatives, use the normalized name and text as representative fields and inspect the deduplicated media list without assuming it is a complete per-variant table.
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 Company Ads API — Collect public ads for one advertiser Page ID with creative, delivery, market, media, CTA, and visible signal fields.