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.
https://api.scrapeadlibrary.com/v1
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.
| Endpoint | Description | Credits |
|---|---|---|
| GET /v1/ads/search | Search ads by keyword or advertiser page, with filters | 1 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 spend | 2 credits |
| GET /v1/pages/{page_id} | Advertiser page profile | 1 credit |
| GET /v1/pages/{page_id}/ads | All ads of one advertiser page | 1 credit per 10 items returned (rounded up; an empty result is free) |
| GET /v1/pages/search | Advertisers that ran ads matching a keyword | 1 credit per 10 items returned (rounded up; an empty result is free) |
| any non-2xx | Errors of any kind | 0 |
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:
| Header | Description |
|---|---|
| X-Credits-Used | Credits charged for this request |
| X-Credits-Remaining | Credits 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.
| Status | Error Code | Description |
|---|---|---|
| 400 | invalid_parameter | A parameter is missing or invalid; details.param names it |
| 400 | cursor_mismatch | The cursor was used with different parameters than the request that produced it |
| 401 | missing_api_key | No API key in X-API-Key or Authorization |
| 401 | invalid_api_key | The API key does not exist or was revoked |
| 402 | insufficient_credits | The account has no credits left |
| 404 | ad_not_found | No ad with this ID in the Ad Library |
| 404 | page_not_found | No advertiser page with this ID |
| 404 | not_found | Unknown path (check the URL and the /v1 prefix) |
| 405 | method_not_allowed | Every endpoint is GET |
| 410 | cursor_expired | The cursor is older than 1 hour |
| 429 | rate_limit_exceeded | Too many requests for this API key |
| 429 | insufficient_credits_retry_later | The key kept retrying with no credits and is paused |
| 502 | upstream_schema_changed | The Ad Library changed its format; we are alerted automatically |
| 503 | upstream_unavailable | The Ad Library is temporarily unreachable (temporary block, all fetchers failed) |
| 504 | upstream_timeout | The Ad Library did not answer in time |
| 500 | internal_server_error | Unexpected error on our side |
See the Error Handling page for when to retry.
Ads
/v1/ads/search1 credit per 10 ads returned, rounded up; 0 for an empty resultSearch the ads of the Meta Ad Library by keyword or advertiser page, with filters. Paginated with cursors.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| q | string | required | Keyword (1-100 characters). Required unless page_id is given |
| page_id | digits | - | Restrict the search to one advertiser page |
| country | string | ALL | ISO 3166 alpha-2 country code (e.g. IT, US) or ALL |
| status | enum | active | active | inactive | all |
| ad_type | enum | all | all | political (political and issue ads) |
| media_type | enum | all | all | image | video | meme | none |
| platforms | csv | all | Any of facebook, instagram, messenger, audience_network, threads |
| languages | csv | all | ISO 639-1 language codes (e.g. en,it) |
| active_from | date | - | YYYY-MM-DD. With active_to: ads that were running at some point in the window |
| active_to | date | - | YYYY-MM-DD, end of the window |
| match | enum | any | any | exact (exact phrase) |
| sort | enum | relevance | relevance | impressions (most impressions first) |
| limit | integer | 30 | Ads per page, 1-50 |
| cursor | string | - | next_cursor of the previous page; the other parameters must be identical |
Request
curl "https://api.scrapeadlibrary.com/v1/ads/search?q=nike&country=IT&status=active&media_type=video&limit=30" \
-H "X-API-Key: sal_your_api_key"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"
}Response Fields
| Field | Type | Description |
|---|---|---|
| data | Ad[] | The ads of this page of results |
| total_estimate | integer | Estimated total number of matching ads |
| has_more | boolean | Whether another page exists |
| next_cursor | string | null | Pass it as cursor to get the next page (valid for 1 hour) |
| credits_used | integer | Credits charged for this call |
| cached | boolean | Whether the response came from our cache |
| media_expires_at | string | null | Earliest expiry of the media URLs in the response |
/v1/ads/{ad_id}2 creditsFull 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
| Parameter | Type | Default | Description |
|---|---|---|---|
| ad_id | string | required | Ad Library ID (the id of an Ad) |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| country | string | ALL | ISO 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
{
"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
| Field | Type | Description |
|---|---|---|
| advertiser | Page | Full profile of the advertiser page |
| payers | object[] | Payer and beneficiary declared for the ad |
| transparency.eu | object | null | EU (DSA) data: reach, gender, age_min, age_max, locations, breakdown by country, age and gender |
| transparency.uk | object | null | Same shape, for the United Kingdom |
| about | string | null | About text of the page |
| removed | boolean | Whether Meta took the ad down |
Advertiser Pages
/v1/pages/{page_id}1 creditProfile of an advertiser page: category, likes, linked Instagram account, verification and estimated active ads.
Path Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| page_id | digits | required | Page ID (page.id of an Ad) |
Request
curl "https://api.scrapeadlibrary.com/v1/pages/15087023444" \
-H "X-API-Key: sal_your_api_key"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
}/v1/pages/{page_id}/ads1 credit per 10 ads returned, rounded up; 0 for an empty resultAll the ads of one advertiser page. Same parameters as the ad search except q and page_id, same response.
Path Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| page_id | digits | required | Page ID |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| country | string | ALL | ISO 3166 alpha-2 country code (e.g. IT, US) or ALL |
| status | enum | active | active | inactive | all |
| ad_type | enum | all | all | political (political and issue ads) |
| media_type | enum | all | all | image | video | meme | none |
| platforms | csv | all | Any of facebook, instagram, messenger, audience_network, threads |
| languages | csv | all | ISO 639-1 language codes (e.g. en,it) |
| active_from | date | - | YYYY-MM-DD. With active_to: ads that were running at some point in the window |
| active_to | date | - | YYYY-MM-DD, end of the window |
| match | enum | any | any | exact (exact phrase) |
| sort | enum | relevance | relevance | impressions (most impressions first) |
| limit | integer | 30 | Ads per page, 1-50 |
| cursor | string | - | 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
{
"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"
}/v1/pages/search1 credit per 10 pages returned, rounded up; 0 for an empty resultAdvertisers that ran ads matching a keyword, deduplicated by page.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| q | string | required | Keyword (1-100 characters) |
| country | string | ALL | ISO 3166 alpha-2 country code or ALL |
| limit | integer | 10 | Advertisers to return, 1-30 |
Request
curl "https://api.scrapeadlibrary.com/v1/pages/search?q=running%20shoes&country=US" \
-H "X-API-Key: sal_your_api_key"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
}Health
/healthfreeService status. No authentication, no credits.
{ "status": "healthy" }Objects
AdOne ad, as returned in lists.
| Field | Type | Description |
|---|---|---|
| id | string | Ad Library ID of the ad |
| url | string | Link to the ad in the public Meta Ad Library |
| page | object | Advertiser: id, name, profile_picture_url, is_person, categories, like_count |
| status | enum | active | inactive |
| started_at | string | When the ad started running (ISO 8601 UTC) |
| ended_at | string | null | When the ad stopped running, null while active |
| platforms | string[] | facebook, instagram, messenger, audience_network, threads |
| format | enum | image | video | carousel | dco | dpa | text | other |
| body | string | null | Main text of the ad |
| title | string | null | Headline |
| caption | string | null | Display domain of the link (e.g. play.google.com) |
| link_url | string | null | Landing page |
| link_description | string | null | Text under the headline |
| cta | object | null | Call to action: { text, type } |
| images | Media[] | Images of the creative |
| videos | Media[] | Videos of the creative |
| cards | Card[] | Carousel cards |
| variants_count | integer | Number of ads sharing the same creative |
| collation_id | string | null | ID of the group of variants |
| categories | string[] | Ad categories, e.g. political, housing, employment, unknown |
| countries | string[] | Targeted or reached countries, when exposed |
| political | object | null | Spend, impressions, reach and disclaimer of political and issue ads |
| contains_ai_generated_media | boolean | Whether the advertiser declared AI-generated media |
{
"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": {
"spend": { "lower": 7000, "upper": 8000, "currency": "EUR", "text": "€7K - €8K" },
"impressions": { "text": ">1M" },
"reach": { "text": ">1M" },
"disclaimer": "Paid for by ..."
}MediaAn image or video of a creative.
{
"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
}CardOne card of a carousel.
{
"title": "...", "body": "...", "caption": "...", "link_url": "...",
"cta": { "text": "Shop now", "type": "shop_now" } | null,
"image": Media | null,
"video": Media | null
}AdDetailAd plus the fields below, returned by GET /v1/ads/{ad_id}.
| Field | Type | Description |
|---|---|---|
| advertiser | Page | Full profile of the advertiser page |
| payers | object[] | Payer and beneficiary declared for the ad |
| transparency.eu | object | null | EU (DSA) data: reach, gender, age_min, age_max, locations, breakdown by country, age and gender |
| transparency.uk | object | null | Same shape, for the United Kingdom |
| about | string | null | About text of the page |
| removed | boolean | Whether Meta took the ad down |
PageAn advertiser page, returned by GET /v1/pages/{page_id}.
| Field | Type | Description |
|---|---|---|
| id | string | Page ID |
| name | string | Page name |
| is_person | boolean | Whether the advertiser is a person profile |
| category | string | null | Page category |
| like_count | integer | Page likes |
| object | null | Linked Instagram account: username, followers, verified | |
| verified | boolean | Verified badge |
| profile_picture_url | string | null | Profile picture (null for person profiles) |
| cover_photo_url | string | null | Cover photo |
| about | string | null | About text |
| deleted | boolean | Whether the page has been deleted |
| active_ads_estimate | integer | null | Estimated number of active ads (null when unknown) |
| url | string | All the ads of the page in the public Meta Ad Library |
PageSummaryAn advertiser in the results of GET /v1/pages/search.
| Field | Type | Description |
|---|---|---|
| id | string | Page ID |
| name | string | Page name |
| is_person | boolean | Whether the advertiser is a person profile |
| profile_picture_url | string | null | Profile picture (null for person profiles) |
| categories | string[] | Page categories |
| like_count | integer | Page likes |
| ads_in_results | integer | How many of the matching ads belong to this page |