Code Examples

Complete examples with cURL and the official SDKs for every endpoint.

Each example runs as is once you replace the sample key with your own: create one for free in the dashboard, then either paste it into the code or export it as SCRAPEADLIBRARY_API_KEY, which both SDKs read automatically. The responses shown under each example are shortened; the API reference lists every field. Lists cost 1 credit per 10 items returned, an ad with its details 2 credits and an advertiser page 1; an empty result or an error never costs anything.

PythonPyPI
pip install scrapeadlibrary
TypeScriptnpm
npm install scrapeadlibrary

Search Ads

Active ads that mention a keyword in one country, filtered by media type and platform.

curl "https://api.scrapeadlibrary.com/v1/ads/search?q=nike&country=IT&media_type=video&platforms=instagram&limit=30" \
  -H "X-API-Key: sal_your_api_key"
Example Response
{
  "data": [ { "id": "1550534860016399", "page": { "id": "115939511520844", "name": "Perfect themes", ... }, ... } ],
  "total_estimate": 6780,
  "has_more": true,
  "next_cursor": "c_9Xk2a8ZqLw",
  "credits_used": 3,
  "cached": false,
  "media_expires_at": "2026-11-25T18:00:00Z"
}

Paginate Through Results

Pass next_cursor back as cursor with the same parameters until has_more is false, or let the SDK iterator do it. Every page is billed by the ads it returns.

# First page
curl "https://api.scrapeadlibrary.com/v1/ads/search?q=nike&country=IT&limit=50" \
  -H "X-API-Key: sal_your_api_key"

# Next page: same parameters + the cursor (valid for 1 hour)
curl "https://api.scrapeadlibrary.com/v1/ads/search?q=nike&country=IT&limit=50&cursor=c_9Xk2a8ZqLw" \
  -H "X-API-Key: sal_your_api_key"

Ad Detail with EU Transparency Data

Payer, beneficiary, reach and the audience breakdown by country, age and gender published under the EU Digital Services Act.

curl "https://api.scrapeadlibrary.com/v1/ads/1550534860016399?country=IT" \
  -H "X-API-Key: sal_your_api_key"
Example Response
{
  "data": {
    "id": "1550534860016399",
    ...every field of the Ad object...,
    "advertiser": { ...Page object... },
    "payers": [ { "payer": "Company Ltd", "beneficiary": "Company Ltd" } ],
    "transparency": {
      "eu": {
        "reach": 65104,
        "gender": "all",
        "age_min": 21,
        "age_max": 65,
        "locations": [ { "name": "Italy", "type": "country", "excluded": false } ],
        "breakdown": [
          { "country": "IT", "age_range": "18-24", "male": 31, "female": 1, "unknown": 0 }
        ]
      },
      "uk": null
    },
    "about": "Page about text",
    "removed": false
  },
  "credits_used": 2,
  "cached": false,
  "media_expires_at": "2026-11-25T18:00:00Z"
}

Advertiser Page and Its Ads

The profile of an advertiser and every ad it runs, active or not.

curl "https://api.scrapeadlibrary.com/v1/pages/15087023444" \
  -H "X-API-Key: sal_your_api_key"

curl "https://api.scrapeadlibrary.com/v1/pages/15087023444/ads?status=all&limit=50" \
  -H "X-API-Key: sal_your_api_key"
Example Response
{
  "data": {
    "id": "15087023444",
    "name": "Nike",
    "is_person": false,
    "category": "Sportswear Store",
    "like_count": 39000000,
    "instagram": { "username": "nike", "followers": 300000000, "verified": true },
    "verified": true,
    "profile_picture_url": "https://scontent.xx.fbcdn.net/...",
    "cover_photo_url": "https://scontent.xx.fbcdn.net/...",
    "about": "...",
    "deleted": false,
    "active_ads_estimate": 14386,
    "url": "https://www.facebook.com/ads/library/?view_all_page_id=15087023444"
  },
  "credits_used": 1,
  "cached": false
}

Find Advertisers

Advertisers that ran ads matching a keyword, with how many of the matching ads are theirs.

curl "https://api.scrapeadlibrary.com/v1/pages/search?q=running%20shoes&country=US&limit=10" \
  -H "X-API-Key: sal_your_api_key"
Example Response
{
  "data": [
    {
      "id": "15087023444",
      "name": "Nike",
      "is_person": false,
      "profile_picture_url": "https://scontent.xx.fbcdn.net/...",
      "categories": ["Sportswear Store"],
      "like_count": 39000000,
      "ads_in_results": 4
    }
  ],
  "credits_used": 1,
  "cached": false
}

Handle Errors and Retries

Errors are never billed. Retry 429, 503 and 504 after a pause (429 tells you how long in Retry-After); 402 means it is time to top up.

import time
import requests

def get(path, params, retries=4):
    for attempt in range(retries):
        r = requests.get(
            f"https://api.scrapeadlibrary.com{path}",
            params=params,
            headers={"X-API-Key": "sal_your_api_key"},
            timeout=60,
        )
        if r.ok:
            print("credits left:", r.headers.get("X-Credits-Remaining"))
            return r.json()
        error = r.json().get("error")
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", 5)))
        elif r.status_code in (503, 504):
            time.sleep(2 ** attempt)
        elif r.status_code == 402:
            raise RuntimeError("Out of credits: top up in the dashboard")
        else:
            raise RuntimeError(f"{r.status_code} {error}: {r.json().get('message')}")
    raise RuntimeError("Gave up after retries")

ads = get("/v1/ads/search", {"q": "nike", "country": "IT"})

Tips for Large Pulls

  • Ask for 50 ads per page when you want everything: the price depends on the ads returned, not on the number of calls, so bigger pages simply mean fewer round trips.
  • Keep the parameters identical while you follow next_cursor, and finish a walk within an hour: cursors expire after that and the API answers 410 cursor_expired.
  • Results are cached for 24 hours, so running the same search twice in a day is fast. Data is fresh enough for monitoring, but schedule daily jobs rather than polling every few minutes.
  • Download the images and videos you want to keep: their links expire after a few days, at the time given in expires_at.

Next Steps