ScrapeAdLibrary Python SDK
Official Python SDK for the ScrapeAdLibrary API: search the public Meta Ad Library (Facebook, Instagram, Messenger, Audience Network, Threads), read full ad details with EU/UK transparency data, and look up advertiser pages.
Installation
pip install scrapeadlibrary
Quick Start
from scrapeadlibrary import ScrapeAdLibrary
client = ScrapeAdLibrary(api_key="sal_your_api_key") # or set SCRAPEADLIBRARY_API_KEY
page = client.ads.search(q="running shoes", country="IT", limit=10)
print(page.total_estimate, "ads found")
for ad in page:
print(ad.page.name, "|", ad.format, "|", ad.body)
for image in ad.images:
print(" ", image.url) # signed CDN URL, valid until image.expires_at
print(client.credits_remaining) # from the X-Credits-Remaining header
Async Usage
import asyncio
from scrapeadlibrary import AsyncScrapeAdLibrary
async def main():
async with AsyncScrapeAdLibrary() as client:
page = await client.ads.search(q="running shoes", country="US")
async for ad in client.ads.search_all(q="running shoes", max_items=100):
print(ad.id, ad.started_at)
asyncio.run(main())
Configuration
| Argument | Env var | Default |
|---|---|---|
api_key |
SCRAPEADLIBRARY_API_KEY |
required (keys start with sal_) |
base_url |
SCRAPEADLIBRARY_BASE_URL |
https://api.scrapeadlibrary.com |
timeout |
30.0 seconds |
|
max_retries |
2 (on 429, 500, 503, 504 and network errors, honouring Retry-After) |
API Reference
Ads
# Search (1 credit per 10 ads returned, rounded up; empty result = 0)
page = client.ads.search(
q="running shoes", # keyword, required unless page_id is given
page_id=None, # restrict to one advertiser
country="IT", # ISO-3166 alpha-2 or "ALL" (default)
status="active", # active (default) | inactive | all
ad_type="all", # all (default) | political
media_type="video", # all | image | video | meme | none
platforms=["facebook", "instagram"],
languages=["it"],
active_from="2026-10-01", # str or datetime.date
active_to="2026-11-01",
match="exact", # any (default) | exact phrase
sort="impressions", # relevance (default) | impressions
limit=30, # 1-50
)
page.data, page.total_estimate, page.has_more, page.next_cursor
page.credits_used, page.cached, page.media_expires_at, page.credits_remaining
# Next page: same params + cursor
next_page = client.ads.search(q="running shoes", country="IT", cursor=page.next_cursor)
# Iterate over all results, following cursors
for ad in client.ads.search_all(q="running shoes", country="IT", max_items=200):
...
# Full detail of one ad (2 credits): advertiser, payers, EU (DSA) / UK transparency
detail = client.ads.get("1550534860016399", country="IT").data
print(detail.advertiser.name, detail.payers)
if detail.transparency and detail.transparency.eu:
print("EU reach:", detail.transparency.eu.reach)
Pages (advertisers)
# Advertiser profile (1 credit)
nike = client.pages.get("15087023444").data
print(nike.name, nike.like_count, nike.active_ads_estimate)
# Ads of one advertiser (same filters as ads.search, without q)
page = client.pages.ads("15087023444", country="US", media_type="video")
for ad in client.pages.ads_all("15087023444", max_items=100):
...
# Advertisers that ran ads matching a keyword (1 credit per 10 results)
for adv in client.pages.search("sneakers", country="IT", limit=10):
print(adv.id, adv.name, adv.ads_in_results)
Models
Responses are typed dataclasses: Ad, AdDetail, Media, Card, Page, PageSummary,
Transparency, ... Parsing is tolerant: unknown fields never break the SDK and the original JSON is
always available as model.raw (or model.to_dict()).
Media URLs are signed CDN links that expire (Media.expires_at, page.media_expires_at, usually
after a few days): download what you need to keep.
Error Handling
from scrapeadlibrary import (
ScrapeAdLibrary,
AdNotFoundError,
InsufficientCreditsError,
RateLimitError,
CursorError,
)
client = ScrapeAdLibrary()
try:
ad = client.ads.get("123").data
except AdNotFoundError:
print("No such ad")
except InsufficientCreditsError:
print("Top up your credits")
except RateLimitError as e:
print(f"Retry in {e.retry_after}s")
| Exception | HTTP | error codes |
|---|---|---|
ScrapeAdLibraryError |
any | base class (.message, .status_code, .code, .details) |
InvalidParameterError |
400 | invalid_parameter (.param) |
CursorError |
400 / 410 | cursor_mismatch, cursor_expired |
AuthenticationError |
401 | missing_api_key, invalid_api_key |
InsufficientCreditsError |
402 | insufficient_credits |
NotFoundError → AdNotFoundError, PageNotFoundError |
404 | ad_not_found, page_not_found |
RateLimitError |
429 | rate_limit_exceeded, insufficient_credits_retry_later (.retry_after) |
UpstreamError |
502 / 503 / 504 | upstream_schema_changed, upstream_unavailable, upstream_timeout |
InternalServerError |
500 | internal_server_error |
APIConnectionError |
— | network error or timeout after retries |
Failed requests cost 0 credits.
Development
uv venv && uv pip install -e ".[dev]"
.venv/bin/pytest
.venv/bin/ruff check . && .venv/bin/ruff format --check .
# Live check against the real API (spends a few credits)
SCRAPEADLIBRARY_API_KEY=sal_xxx .venv/bin/python examples_live.py
License
MIT
Metadata
Release files for scrapeadlibrary 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| scrapeadlibrary-0.1.0.tar.gz | 20.5 kB | Without provenance | Details for scrapeadlibrary-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| scrapeadlibrary-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for scrapeadlibrary-0.1.0-py3-none-any.whl |
Total release size: 39.0 kB
Release files / scrapeadlibrary-0.1.0.tar.gz
| Download URL | scrapeadlibrary-0.1.0.tar.gz |
|---|---|
| Size | 20.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
66d7f730db301f26f70b7335cf3a9c3bf627e634174ad9ca3c285a2b5d3e04b1
|
|
BLAKE2b-256 checksum How to use checksums |
13a1acfaef3330c7fa7c7f9593a4d8c94814e74130fb26714b3223567e9c309d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.12 {"installer":{"name":"uv","version":"0.10.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / scrapeadlibrary-0.1.0-py3-none-any.whl
| Download URL | scrapeadlibrary-0.1.0-py3-none-any.whl |
|---|---|
| Size | 18.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5aa54d63b9a22e2f95b97c7355ba7190b5f4f41516806f5d217b3c67420740f9
|
|
BLAKE2b-256 checksum How to use checksums |
c58f2bb613ebcb93f895917ffe63b9574529db1f324a092a6f78fc4f4f19172d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.12 {"installer":{"name":"uv","version":"0.10.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for scrapeadlibrary 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.