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