Skip to main content

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)

Source distribution for scrapeadlibrary 0.1.0
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)

Table of built distributions (wheels) for scrapeadlibrary 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page