Skip to content
scrapeatlas.Dashboard

Ad libraries

Meta Ads Library API

Search ads and advertisers, retrieve ad creatives, and list a company’s ads.

8 endpointsx-api-key

Search Meta Ad Library, discover advertisers and retrieve ads, creative variants, transcripts and regional transparency information.

API availability: Available

Base URL · local workerhttp://localhost:3023Public API: https://api.scrapeatlas.com.
Authenticationx-api-keyCustomer key from your account. See Authentication.

Endpoints

GET/v1/facebook/adLibrary/search/ads

Search ads

Retrieve one public page with the documented filters and an opaque continuation cursor. Lowercase /adlibrary/ aliases return canonical Post/Author data.

Reference
POST/v1/facebook/adLibrary/search/ads

Search ads with a POST body

Retrieve one public page with the documented filters and an opaque continuation cursor. Lowercase /adlibrary/ aliases return canonical Post/Author data.

Reference
GET/v1/facebook/adLibrary/ad

Ad details

Retrieve an ad with creative variants, payer and beneficiary information, and EU, UK or Brazil transparency. Set includeTranscript=true to transcribe its primary video.

Reference
GET/v1/facebook/adLibrary/search/companies

Find advertisers

Retrieve public advertiser suggestions by name. Company-ad lookup by name requires one case-insensitive exact match; use pageId when names are ambiguous.

Reference
GET/v1/facebook/adLibrary/company/ads

Get company ads

Retrieve public advertiser suggestions or one page of an advertiser’s ads. Company-name lookup requires a unique exact match; use pageId when ambiguous.

Reference
POST/v1/facebook/adLibrary/company/ads

Get company ads with a POST body

Retrieve public advertiser suggestions or one page of an advertiser’s ads. Company-name lookup requires a unique exact match; use pageId when ambiguous.

Reference
POST/v1/facebook/ad-library/companies/ads

Walk compact company ads

Retrieve a page of advertiser archive records as a normalized ads array with compact records and continuation.

Reference
GET/v1/facebook/adLibrary/ad/transcript

Ad video transcript

Return plain speech text from the first available primary or carousel video. Image-only ads and videos without detected speech return transcript_available=false.

Reference

Quick start

Create an API key on your account page, then call the public API. Values below are placeholders.

Terminal
curl "https://api.scrapeatlas.com/v1/facebook/adLibrary/search/ads?query=running" \
  -H "x-api-key: YOUR_API_KEY"

Coverage & limits

  • Browser-backed operations run on a configurable slot count (two by default); a request waits up to 20 seconds in arrival order for a free slot, with at most 24 waiting, and is refused as busy beyond that. 64 warm GraphQL continuations; 45-second retrieval deadline or 180 seconds when transcription is requested.
  • At most 100 upstream requests and 24 MiB total decoded retrieval traffic; each GraphQL continuation response is capped at 2 MiB, plus 32 MiB for one video.
  • At most 100 records, 48 JSON nesting levels and 200,000 nodes. POST bodies are limited to 64 KiB.
  • Transcription supports the first available video up to 180 seconds. Temporary files are deleted after success, failure or cancellation.
  • Optional META_ADS_PROXY_URL with pagination mode by default and configurable META_ADS_PROXY_USERNAME_TEMPLATE. One persistent native session is reused per advertiser walk; a failed transport reconnects once, then rotates the residential session once and resumes the same cursor. Local Whisper model and FFmpeg are required for transcription. Bootstrap credentials are held for ten minutes in bounded process memory. No login, persistent browser profile, database or result cache.
Error codes
12
HTTPfailure.codeMeaning
400invalid_requestInvalid, conflicting or unsupported parameters/cursor.
401unauthorizedMissing or invalid x-api-key.
403restricted_pageSource marks the ad restricted.
404not_foundExplicitly absent ad or no exact company match.
429upstream_rate_limitedMeta rate limit after at most two fresh proxy-session retries; direct egress is never retried on the same IP.
502upstream_error upstream_challenged unsupported_pageSource failed, challenged, or returned unsupported data.
502response_too_large request_limit payload_too_complexAn operation bound was exceeded.
503busyBoth retrieval slots are occupied.
504timeoutThe operation deadline expired.
503transcription_unavailableLocal speech runtime is not configured.
502transcription_failedMedia decoding or speech recognition failed.
422transcription_too_longVideo exceeds the 180-second speech limit.