Search the Facebook Ad Library

Parameters

query

is required. keyword and q are aliases. region is the one country to search. Use a two-letter code, or ALL for every country. The recorded search uses query=nike and region=US.

sort

is relevance, impressions or newest. impressions is most impressions first. newest is most recent. Changing sort restarts the cursor chain. match is any_words or exact_phrase. ad_type is all or political (political and issue ads only). status is active, inactive or all. active_status is an alias of status. media_type is all, image, video, meme, image_and_meme or none. The reference says meme is Meta's word for text on an image. language is a 2-letter code such as EN, ES or FR. start_date and end_date are the impressions window, YYYY-MM-DD.

cursor

pages. The route is also available as POST with a JSON body, for cursors too long for a URL. The recorded GET below is a later page: it includes a cursor. For the first page, send query and region only.

A first page for the recorded query:

1curl -G "https://api.socialscrape.dev/v1/facebook/ad-library/search" \2  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \3  --data-urlencode "query=nike" \4  --data-urlencode "region=US"

The recorded request, cursor included, in three languages:

1curl -G "https://api.socialscrape.dev/v1/facebook/ad-library/search" \2  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \3  --data-urlencode "query=nike" \4  --data-urlencode "region=US" \5  --data-urlencode "cursor=eyJrIjoiZmJhZHMiLCJjIjoiQVFIVHR6TWN1R1ZGekcxSF85UzBpNjN5VTVMYjFzZHFDZmZaRjRYeHRHS205dXlVNG1BTUpkT2F3VEg1YUM4VWdvV2EifQ"

1import os2import requests34params = {5    "query": "nike",6    "region": "US",7    "cursor": "eyJrIjoiZmJhZHMiLCJjIjoiQVFIVHR6TWN1R1ZGekcxSF85UzBpNjN5VTVMYjFzZHFDZmZaRjRYeHRHS205dXlVNG1BTUpkT2F3VEg1YUM4VWdvV2EifQ",8}9res = requests.get(10    "https://api.socialscrape.dev/v1/facebook/ad-library/search",11    headers={"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]},12    params=params,13)14body = res.json()1516if body["ok"]:17    print(body["data"])18else:19    print(body["error"]["code"], body["error"]["message"])

1const url = new URL("https://api.socialscrape.dev/v1/facebook/ad-library/search");2url.search = new URLSearchParams({3  "query": "nike",4  "region": "US",5  "cursor": "eyJrIjoiZmJhZHMiLCJjIjoiQVFIVHR6TWN1R1ZGekcxSF85UzBpNjN5VTVMYjFzZHFDZmZaRjRYeHRHS205dXlVNG1BTUpkT2F3VEg1YUM4VWdvV2EifQ"6}).toString();7const res = await fetch(url, {8  headers: { "x-api-key": process.env.SOCIALSCRAPE_API_KEY! },9});10const body = await res.json();1112if (body.ok) {13  console.log(body.data);14} else {15  console.error(body.error.code, body.error.message);16}

Check ok. invalid_params and not_found are not retryable. rate_limited is.

What an ad contains

data.items are ads. data.object is list. Each ad has:

• object ad, platform, id, url (an Ad Library link).
• advertiser, with its own id, name and url when the library sends them.
• status, started_at, ended_at.
• title, body, cta_text, landing_url, format.
• media: thumbnail_url, video_url, audio_url, image_urls, width, height. Long CDN links expire. extra.media_expires_at is the time on the recording.
• regions, publisher_platforms.
• impressions and spend.

In the recorded sample, impressions and spend are null on the ads shown. The fields exist so a number can be carried when the library publishes one. Null is not a zero. Political and regulated ads add transparency data under extra, including impressions_text, page_spend and reach_estimate on the single-ad endpoint. Do not assume a keyword search of ordinary ads fills spend.

extra on a search hit also includes caption, cards (carousel bodies, titles, cta_text, link_url), categories, collation_count, collation_id, link_description, contains_digital_created_media, contains_sensitive_content and video_urls.

publisher_platforms in the sample lists where the ad ran, such as facebook, instagram and messenger, when the library says so.

One ad

GET /v1/facebook/ad-library/ad

takes id or url. One of them. url is facebook.com/ads/library/?id=.... The response is one ad: page, status, dates and the snapshot (text, images, videos, format, link, call to action). Regulated ads put transparency data in extra.

get_transcript

is accepted and does not transcribe the video. The reference says a video ad's transcript is its own call, ad/transcript, billed as AI transcription, and this flag only adds a pointer in extra.transcript_hint. Leave the flag off unless you want that pointer.

The recorded ad request uses an id. It is 1 credit on success, cacheable for 30 days like the search.