Social Fetch
Get API key
Facebook hub

Facebook Ad Library Ad API

Resolve one Meta Ad Library creative by archive id or public URL — structured ad fields in the shared Social Fetch envelope.

GET /v1/facebook/ad-library/ads

1 credit per successful request.

Try in playgroundFull API docs

About this endpoint

Once you already know which Facebook Ad Library entry you care about, you do not need another keyword search. You need the archive id (or the public Ad Library URL someone pasted into Slack) turned into a stable JSON object you can store, compare, or hand to a review queue.

`GET /v1/facebook/ad-library/ads` requires either `adId` or `url`. Pass the Meta archive id when you have it; pass the public Ad Library detail URL when that is what you collected. Optional `includeTranscript=true` asks for plain-text speech from the ad video when transcription is available; `trim=true` requests a smaller upstream payload before normalization. The response uses the shared Social Fetch envelope: `data.lookupStatus` is `found` or `not_found`, `data.ad` holds the ad object when found (otherwise null), and `data.transcript` is the optional transcript string or null. Bill from `meta.creditsCharged`.

This route is single-ad detail. Keyword discovery is `GET /v1/facebook/ad-library/ads/search`. Advertiser name lookup and company ad lists are separate company routes under the same Facebook tag. One API key covers all of them.

Facebook Ad Library Ad API FAQ

What does the Facebook Ad Library Ad API return?

A single-ad lookup under data: lookupStatus (found or not_found), ad (the Ad Library object when found, otherwise null), and transcript (plain text when you requested includeTranscript and speech was available, otherwise null). Each response uses the shared Social Fetch envelope with meta.requestId and meta.creditsCharged.

How do I fetch one Facebook Ad Library ad?

Send GET /v1/facebook/ad-library/ads with x-api-key and either adId (the archive id) or url (the public Ad Library detail URL). Optionally add includeTranscript and trim. Exactly one of adId or url is required.

How much does a Facebook Ad Library ad lookup cost?

Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged — that field is the billing source of truth.

Is this the same as Facebook Ad Library keyword search?

No. GET /v1/facebook/ad-library/ads returns one ad when you already have an archive id or Ad Library URL. GET /v1/facebook/ad-library/ads/search finds ads by keyword and filters.

Can I get a transcript of the ad video?

Yes. Set includeTranscript=true. When speech is detected and transcription succeeds, data.transcript is plain text. It may be null when speech is not detected, the video exceeds supported length, or transcription is otherwise unavailable.

What happens if the ad id or URL is wrong?

A completed lookup can still return HTTP success with data.lookupStatus set to not_found and data.ad null. Check lookupStatus before treating the response as a resolved creative. Use meta.requestId when you need support on a failed or unexpected call.

Do I need a Meta ads account or Marketing API token?

No. You authenticate to Social Fetch with an API key. The route reads a public Ad Library ad by id or URL; it does not act on behalf of an ads account you manage.

Other Facebook endpoints