Ads

Search the Meta Ad Library for ads other brands are running, keep the ones worth learning from, and turn one into a brief for your own brand. Searching, saving and briefs cost no credits.

Meta only shares commercial ads that were shown in the EU and UK. An advertiser that only runs ads in the US returns nothing. Meta returns the ad text, delivery dates and platforms, not the image or video; sourceUrl opens the ad on Meta.

Search ads (GET /ads/search, scope ads:read)

Search by words in the ad text:

bash 
curl -s "https://faceless.so/api/v1/ads/search?q=faceless%20videos" \
  -H "Authorization: Bearer $FACELESS_API_KEY"

Or by one advertiser's exact Facebook Page ID, the view_all_page_id in its Ad Library link:

bash 
curl -s "https://faceless.so/api/v1/ads/search?pageId=532679353271897&mediaType=VIDEO" \
  -H "Authorization: Bearer $FACELESS_API_KEY"

Parameters:

  • q or pageId (one of them, required).
  • country: EU_UK (default, every EU country and the UK) or one country code such as DE.
  • mediaType: ALL (default), IMAGE or VIDEO.
  • platform: ALL (default), FACEBOOK, INSTAGRAM, MESSENGER, AUDIENCE_NETWORK, THREADS or WHATSAPP.
  • status: ACTIVE (default, running now), INACTIVE or ALL.
  • cursor: the nextCursor of the previous page. Keep every other parameter the same.

A page holds up to 25 ads, a resultToken and a nextCursor. The resultToken is what lets you save or brief an ad from that page, and it lasts 15 minutes; after that, search again. startedAt and stoppedAt are Meta's delivery dates. A long-running ad is a hint, not proof, that it works.

Each team has a daily search allowance (50 fresh searches by default). Repeating a search from the last 15 minutes is served from cache and does not count. When the allowance is used up the answer is 429 with ads_daily_limit.

Save and list ads (POST /saved-ads, GET /saved-ads, DELETE /saved-ads/{id})

bash 
curl -s -X POST https://faceless.so/api/v1/saved-ads \
  -H "Authorization: Bearer $FACELESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"adId": "2716161098763684", "resultToken": "22df1b25-533f-4bd7-862a-aedc4a4ea0cc"}'

Saving the same ad twice returns the first save. A team keeps up to 500 saved ads. GET /saved-ads lists them newest first, 24 per page, with advertisers for filtering by pageId. Saved ads stay available when fresh search is paused.

Write a brief for your brand (POST /ads/briefs, scope ads:write)

bash 
curl -s -X POST https://faceless.so/api/v1/ads/briefs \
  -H "Authorization: Bearer $FACELESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "adId": "2716161098763684",
    "resultToken": "22df1b25-533f-4bd7-862a-aedc4a4ea0cc",
    "target": "product-video",
    "brand": { "name": "Acme Coffee", "description": "Small-batch coffee roasted to order and shipped within two days.", "website": "acme.coffee" }
  }'

The brief keeps the ad's approach (the kind of hook, the structure, the angle) and writes everything else from brand.description. The advertiser's name, offers, prices, reviews and results never carry over, and nothing is invented; put a real offer in notes if you want it used. target sizes the script: motion (20 seconds), product-video (30 seconds), ugc (20 seconds) or image (one supporting line). Use the brief's script with createVideo. Send savedId instead of resultToken for a saved ad. 30 briefs per hour.

CLI

bash 
faceless ads search "faceless videos" --media VIDEO
faceless ads save 2716161098763684 --result-token 22df1b25-533f-4bd7-862a-aedc4a4ea0cc
faceless ads saved
faceless ads brief 2716161098763684 --result-token 22df1b25-... --target product-video --brand "Acme Coffee" --about "Small-batch coffee roasted to order."