Facebook Ad Library Ad API

Facebook Ad Library Ad

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

How to Use

Submit one public Ad Library URL, track the asynchronous task, and read the normalized ad record from the standard result envelope.

1. Prepare one public Facebook Ad Library URL whose path is /ads/library and whose query contains a numeric id.
2. Submit url to /v1/facebook-ad-library/ad and capture the returned task_id.
3. Poll /v1/tasks/{task_id} until the task succeeds or returns a failure.
4. 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 item

Best 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