Skip to main content

facebook-ads-library-api (Python)

Search the Meta Ads Library (every ad running on Facebook, Instagram, Messenger and WhatsApp) from Python: by keyword or advertiser, page through results, export to CSV. Includes the facebook-ads-library command.

No Meta developer app, no access-token review, commercial ads in every country. The data comes from the SocialAPIs REST API: get a free API key (200 calls/month, no card).

pip install facebook-ads-library-api
export SOCIALAPIS_TOKEN=your_key
from facebook_ads_library_api import AdsLibrary

lib = AdsLibrary()  # or AdsLibrary(api_token="...")

# Ads about a topic (each page = 1 call)
for ad in lib.search("running shoes", country="US", pages=2):
    print(ad["ad_archive_id"], ad.get("page_name"))

# Every ad of one advertiser: ad_page_id, Page URL or username
ads = list(lib.advertiser_ads("nike", active_status="ALL"))

# Flat rows: ad_archive_id, advertiser, headline, text, cta, platforms,
# start_date, landing_domain, ads_library_url
import pandas as pd
df = pd.DataFrame(AdsLibrary.rows(ads))

Other methods: find_advertisers(name), resolve_ad_page_id(page), ad_details(ad_archive_id), page_details(page_id), countries(), search_pages(...) (raw answers).

Options: country (two-letter code or ALL; default US for a keyword, ALL for an advertiser), active_status (Active, Inactive, ALL), sort (impressions, recent), after / before (YYYY-MM-DD), pages (default 1).

Command line

facebook-ads-library search "running shoes" --country US --pages 2 --out ads.csv
facebook-ads-library advertiser nike --status ALL --format jsonl
facebook-ads-library ad 1234567890123456
facebook-ads-library countries

Costs

1 credit per API call; a search makes at most pages calls. Failed calls (4xx / 5xx) are not charged. Pricing. Errors raise the socialapis exceptions (AuthenticationError, InsufficientCreditsError, RateLimitError, …).

You are responsible for how you use public ad data, including personal data rules (GDPR) where they apply. MIT license.

Metadata

Release files for facebook-ads-library-api 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 facebook-ads-library-api 0.1.0
File Size Uploaded Provenance Actions
facebook_ads_library_api-0.1.0.tar.gz 10.5 kB With provenance Details for facebook_ads_library_api-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for facebook-ads-library-api 0.1.0
File Interpreter ABI Platform Actions
facebook_ads_library_api-0.1.0-py3-none-any.whl Python 3 none any Details for facebook_ads_library_api-0.1.0-py3-none-any.whl

Total release size: 22.5 kB

Release files / facebook_ads_library_api-0.1.0.tar.gz

Download URL facebook_ads_library_api-0.1.0.tar.gz
Size 10.5 kB
Tags Source
SHA-256 checksum
How to use checksums
3db5331f80e1a3bf5f741c17ecc7680e2bd02a9fb6c1c4eecdece578b41a7e40
BLAKE2b-256 checksum
How to use checksums
009ceafefcf7d63c546886e0024866dfd9418a8152edf285905af8e502fe01db
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / facebook_ads_library_api-0.1.0-py3-none-any.whl

Download URL facebook_ads_library_api-0.1.0-py3-none-any.whl
Size 12.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9717971cafb0955eb34d7c842115fde50797b29344bd206eb25b01c357004d45
BLAKE2b-256 checksum
How to use checksums
ce1d57a399a63e6d32867546b0e0043d41a00b204dea6675ef9419b1735fc34e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for facebook-ads-library-api 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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for facebook_ads_library_api-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

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 Full 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