Social Fetch
Start for freeStart free
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 Failed requests are free

Try in playgroundFull API docs

About this endpoint

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 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; it includes brandedContent for paid partnership ads and euTransparency with reach, age, gender, locations and payer for ads delivered in the EU or UK), 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