API Reference

Complete reference for every endpoint, parameter and response object. Data comes from the public Meta Ad Library and is returned in a stable format of our own.

Base URL

https://api.scrapeadlibrary.com/v1

Authentication

X-API-Key: sal_… or Bearer token

All timestamps are ISO 8601 UTC strings (2026-11-21T00:00:00Z) and all enums are lowercase snake_case. See Authentication for the API key.

Endpoints and Credits

You pay for the data returned, not per call. Only successful (2xx) responses cost credits: errors cost 0.

EndpointDescriptionCredits
GET /v1/ads/searchSearch ads by keyword or advertiser page, with filters1 credit per 10 items returned (rounded up; an empty result is free)
GET /v1/ads/{ad_id}Full ad detail with EU/UK transparency data, payers and political spend2 credits
GET /v1/pages/{page_id}Advertiser page profile1 credit
GET /v1/pages/{page_id}/adsAll ads of one advertiser page1 credit per 10 items returned (rounded up; an empty result is free)
GET /v1/pages/searchAdvertisers that ran ads matching a keyword1 credit per 10 items returned (rounded up; an empty result is free)
any non-2xxErrors of any kind0

A list with 30 ads costs 3 credits, an empty list or one with up to 10 items costs 1. Before fetching, limit is lowered so that the maximum possible cost does not exceed your balance (limit ≤ credits × 10); with 0 credits you get 402 insufficient_credits.

Response Headers

Every successful response includes these headers:

HeaderDescription
X-Credits-UsedCredits charged for this request
X-Credits-RemainingCredits left after this request

Pagination

List endpoints use cursors. When has_more is true, repeat the same request with cursor=next_cursor. The other parameters must stay identical (otherwise 400 cursor_mismatch) and a cursor is valid for 1 hour (then 410 cursor_expired). The SDKs do this for you with search_all / searchAll.

Media URLs Expire

Image and video URLs point to Meta's CDN and stop working after a few days. Every media object has its own expires_at, and list and detail responses carry media_expires_at, the earliest expiry in the response. Download the files you need to keep before then, or request the ad again to get fresh URLs.

Privacy of Natural Persons

When the advertiser is a person profile (is_person: true), profile_picture_url is always null. Payer and beneficiary names that look like natural persons are replaced by a pseudonym such as "person:3f9a1c2b", stable across responses.

Errors

Errors have the body { "error": "<code>", "message": "…", "details": {…} } and never cost credits.

StatusError CodeDescription
400invalid_parameterA parameter is missing or invalid; details.param names it
400cursor_mismatchThe cursor was used with different parameters than the request that produced it
401missing_api_keyNo API key in X-API-Key or Authorization
401invalid_api_keyThe API key does not exist or was revoked
402insufficient_creditsThe account has no credits left
404ad_not_foundNo ad with this ID in the Ad Library
404page_not_foundNo advertiser page with this ID
404not_foundUnknown path (check the URL and the /v1 prefix)
405method_not_allowedEvery endpoint is GET
410cursor_expiredThe cursor is older than 1 hour
429rate_limit_exceededToo many requests for this API key
429insufficient_credits_retry_laterThe key kept retrying with no credits and is paused
502upstream_schema_changedThe Ad Library changed its format; we are alerted automatically
503upstream_unavailableThe Ad Library is temporarily unreachable (temporary block, all fetchers failed)
504upstream_timeoutThe Ad Library did not answer in time
500internal_server_errorUnexpected error on our side

See the Error Handling page for when to retry.

Ads

GET/v1/ads/{ad_id}2 credits

Full detail of one ad: every Ad field plus the advertiser page, payers and beneficiaries, and the EU (DSA) and UK transparency data (reach, age, gender, locations, breakdown).

Path Parameters

ParameterTypeDefaultDescription
ad_idstringrequiredAd Library ID (the id of an Ad)

Query Parameters

ParameterTypeDefaultDescription
countrystringALLISO 3166 alpha-2 code or ALL: the country the transparency data refers to

Request

curl "https://api.scrapeadlibrary.com/v1/ads/1550534860016399?country=IT" \
  -H "X-API-Key: sal_your_api_key"

Response

200 OK
{
  "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"
}

Fields Added to the Ad Object

FieldTypeDescription
advertiserPageFull profile of the advertiser page
payersobject[]Payer and beneficiary declared for the ad
transparency.euobject | nullEU (DSA) data: reach, gender, age_min, age_max, locations, breakdown by country, age and gender
transparency.ukobject | nullSame shape, for the United Kingdom
aboutstring | nullAbout text of the page
removedbooleanWhether Meta took the ad down

Advertiser Pages

GET/v1/pages/{page_id}1 credit

Profile of an advertiser page: category, likes, linked Instagram account, verification and estimated active ads.

Path Parameters

ParameterTypeDefaultDescription
page_iddigitsrequiredPage ID (page.id of an Ad)

Request

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

Response

200 OK
{
  "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
}
GET/v1/pages/{page_id}/ads1 credit per 10 ads returned, rounded up; 0 for an empty result

All the ads of one advertiser page. Same parameters as the ad search except q and page_id, same response.

Path Parameters

ParameterTypeDefaultDescription
page_iddigitsrequiredPage ID

Query Parameters

ParameterTypeDefaultDescription
countrystringALLISO 3166 alpha-2 country code (e.g. IT, US) or ALL
statusenumactiveactive | inactive | all
ad_typeenumallall | political (political and issue ads)
media_typeenumallall | image | video | meme | none
platformscsvallAny of facebook, instagram, messenger, audience_network, threads
languagescsvallISO 639-1 language codes (e.g. en,it)
active_fromdate-YYYY-MM-DD. With active_to: ads that were running at some point in the window
active_todate-YYYY-MM-DD, end of the window
matchenumanyany | exact (exact phrase)
sortenumrelevancerelevance | impressions (most impressions first)
limitinteger30Ads per page, 1-50
cursorstring-next_cursor of the previous page; the other parameters must be identical

Request

curl "https://api.scrapeadlibrary.com/v1/pages/15087023444/ads?country=ALL&status=all&limit=50" \
  -H "X-API-Key: sal_your_api_key"

Response

200 OK
{
  "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"
}

Health

GET/healthfree

Service status. No authentication, no credits.

Response 200
{ "status": "healthy" }

Objects

Ad

One ad, as returned in lists.

FieldTypeDescription
idstringAd Library ID of the ad
urlstringLink to the ad in the public Meta Ad Library
pageobjectAdvertiser: id, name, profile_picture_url, is_person, categories, like_count
statusenumactive | inactive
started_atstringWhen the ad started running (ISO 8601 UTC)
ended_atstring | nullWhen the ad stopped running, null while active
platformsstring[]facebook, instagram, messenger, audience_network, threads
formatenumimage | video | carousel | dco | dpa | text | other
bodystring | nullMain text of the ad
titlestring | nullHeadline
captionstring | nullDisplay domain of the link (e.g. play.google.com)
link_urlstring | nullLanding page
link_descriptionstring | nullText under the headline
ctaobject | nullCall to action: { text, type }
imagesMedia[]Images of the creative
videosMedia[]Videos of the creative
cardsCard[]Carousel cards
variants_countintegerNumber of ads sharing the same creative
collation_idstring | nullID of the group of variants
categoriesstring[]Ad categories, e.g. political, housing, employment, unknown
countriesstring[]Targeted or reached countries, when exposed
politicalobject | nullSpend, impressions, reach and disclaimer of political and issue ads
contains_ai_generated_mediabooleanWhether the advertiser declared AI-generated media
Ad
{
  "id": "1550534860016399",
  "url": "https://www.facebook.com/ads/library/?id=1550534860016399",
  "page": {
    "id": "115939511520844",
    "name": "Perfect themes",
    "profile_picture_url": "https://scontent.xx.fbcdn.net/...",
    "is_person": false,
    "categories": ["Topic"],
    "like_count": 18520
  },
  "status": "active",
  "started_at": "2026-05-19T07:00:00Z",
  "ended_at": null,
  "platforms": ["facebook", "instagram"],
  "format": "image",
  "body": "Discover our new collection...",
  "title": "Perfect themes",
  "caption": "play.google.com",
  "link_url": "https://play.google.com/store/apps/details?id=...",
  "link_description": null,
  "cta": { "text": "Install now", "type": "install_mobile_app" },
  "images": [
    {
      "type": "image",
      "url": "https://scontent.xx.fbcdn.net/...",
      "preview_url": "https://scontent.xx.fbcdn.net/...",
      "sd_url": null,
      "expires_at": "2026-11-25T18:00:00Z"
    }
  ],
  "videos": [],
  "cards": [],
  "variants_count": 1,
  "collation_id": null,
  "categories": ["unknown"],
  "countries": ["IT"],
  "political": null,
  "contains_ai_generated_media": false
}
political (political and issue ads, otherwise null)
"political": {
  "spend": { "lower": 7000, "upper": 8000, "currency": "EUR", "text": "€7K - €8K" },
  "impressions": { "text": ">1M" },
  "reach": { "text": ">1M" },
  "disclaimer": "Paid for by ..."
}
Media

An image or video of a creative.

Media
{
  "type": "image" | "video",
  "url": "https://scontent...",        // original image or HD video (falls back to SD)
  "preview_url": "https://..." | null, // resized image / video poster
  "sd_url": "https://..." | null,      // video only
  "expires_at": "2026-11-25T18:00:00Z" | null
}
Card

One card of a carousel.

Card
{
  "title": "...", "body": "...", "caption": "...", "link_url": "...",
  "cta": { "text": "Shop now", "type": "shop_now" } | null,
  "image": Media | null,
  "video": Media | null
}
AdDetail

Ad plus the fields below, returned by GET /v1/ads/{ad_id}.

FieldTypeDescription
advertiserPageFull profile of the advertiser page
payersobject[]Payer and beneficiary declared for the ad
transparency.euobject | nullEU (DSA) data: reach, gender, age_min, age_max, locations, breakdown by country, age and gender
transparency.ukobject | nullSame shape, for the United Kingdom
aboutstring | nullAbout text of the page
removedbooleanWhether Meta took the ad down
Page

An advertiser page, returned by GET /v1/pages/{page_id}.

FieldTypeDescription
idstringPage ID
namestringPage name
is_personbooleanWhether the advertiser is a person profile
categorystring | nullPage category
like_countintegerPage likes
instagramobject | nullLinked Instagram account: username, followers, verified
verifiedbooleanVerified badge
profile_picture_urlstring | nullProfile picture (null for person profiles)
cover_photo_urlstring | nullCover photo
aboutstring | nullAbout text
deletedbooleanWhether the page has been deleted
active_ads_estimateinteger | nullEstimated number of active ads (null when unknown)
urlstringAll the ads of the page in the public Meta Ad Library
PageSummary

An advertiser in the results of GET /v1/pages/search.

FieldTypeDescription
idstringPage ID
namestringPage name
is_personbooleanWhether the advertiser is a person profile
profile_picture_urlstring | nullProfile picture (null for person profiles)
categoriesstring[]Page categories
like_countintegerPage likes
ads_in_resultsintegerHow many of the matching ads belong to this page