Facebook Ad Library advertiser search API
Advertisers matching a name: Ad Library page id, category, likes, verification and Instagram details.
- Cost
- 1 credit
- Cached repeats
- 0 creditssend max_age_days, results kept 30 days
- Failed requests
- 0 credits
- Status
- Betashape may still gain fields
Use the page id with company/ads. Meta closes its advertiser typeahead to logged-out visitors, so these are the pages behind the ads a search for the name returns (up to 10, name matches first), each completed from the ad-details query; ad_count is not available.
You send query.
Request
Send your key in the x-api-key header.
curl -G "https://api.socialscrape.io/v1/facebook/ad-library/search/companies" \
-H "x-api-key: $SOCIALSCRAPE_API_KEY" \
--data-urlencode 'query=nike'import os
import requests
params = {
"query": "nike",
}
res = requests.get(
"https://api.socialscrape.io/v1/facebook/ad-library/search/companies",
headers={"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]},
params=params,
timeout=60,
)
body = res.json()
if body["ok"]:
print(body["data"])
else:
print(body["error"]["code"], body["error"]["message"])const url = new URL("https://api.socialscrape.io/v1/facebook/ad-library/search/companies");
url.search = new URLSearchParams({
query: "nike",
}).toString();
const res = await fetch(url, {
headers: { "x-api-key": process.env.SOCIALSCRAPE_API_KEY! },
});
const body = await res.json();
if (body.ok) {
console.log(body.data);
} else {
console.error(body.error.code, body.error.message);
}{
"nodes": [
{
"name": "SocialScrape Facebook Ad Library advertiser search",
"type": "n8n-nodes-base.httpRequest",
"typeVersion": 4.2,
"position": [
0,
0
],
"parameters": {
"method": "GET",
"url": "https://api.socialscrape.io/v1/facebook/ad-library/search/companies",
"sendQuery": true,
"queryParameters": {
"parameters": [
{
"name": "query",
"value": "nike"
}
]
},
"sendHeaders": true,
"headerParameters": {
"parameters": [
{
"name": "x-api-key",
"value": "={{ $env.SOCIALSCRAPE_API_KEY }}"
}
]
}
}
}
],
"connections": {}
}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
query | string | yes | Search terms. Also accepted as keyword, q. |
cursor | string | Opaque cursor from the previous page; pass it back unchanged. Also accepted as continuationToken, continuation_token, next_max_id, max_id, max_cursor, min_time, after, page_token, pageToken, paginationToken, next_page_id, page. |
Every request also accepts trim, raw and max_age_days.
Response
Sample from a recorded response, shortened. Values are public data, not yours.
{
"ok": true,
"credits_charged": 1,
"credits_remaining": 4999,
"cached": false,
"cached_at": null,
"request_id": "req_d42b11390eaf7bfb7c1099f7",
"data": {
"object": "list",
"items": [
{
"object": "advertiser",
"platform": "facebook",
"id": "15087023444",
"name": "Nike",
"url": "https://facebook.com/nike",
"page_id": "15087023444",
"country": null,
"verified": true,
"ad_count": null,
"extra": {
"ads_in_results": 8,
"alias": "nike",
"categories": [
"Sportswear",
"Product/service"
],
"category": "Sportswear Store",
"cover_url": "https://scontent-lga3-3.xx.fbcdn.net/v/t39.30808-6/285211224_10159903868008445_5477337468887983165_n.png?_nc_cat=102&ccb=1-7&_nc_sid=957871&_nc_ohc=53UQOnRTJ...",
"entity_type": "PERSON_PROFILE"
}
},
{
"object": "advertiser",
"platform": "facebook",
"id": "146705838515566",
"name": "Sukeban World",
"url": "https://facebook.com/61551864263186",
"page_id": "146705838515566",
"country": null,
"verified": false,
"ad_count": null,
"extra": {
"ads_in_results": 1,
"categories": [
"Sports league"
],
"category": "Sports league",
"cover_url": "https://scontent-lga3-2.xx.fbcdn.net/v/t39.30808-6/509313384_10106078306132770_1968421726604544597_n.jpg?_nc_cat=105&ccb=1-7&_nc_sid=957871&_nc_ohc=ladQaK-N8...",
"entity_type": "PERSON_PROFILE",
"image_url": "https://scontent-lga3-2.xx.fbcdn.net/v/t39.30808-1/380760046_10105090366990730_3531502738674670798_n.jpg?stp=dst-jpg_s148x148_tt6&_nc_cat=101&ccb=1-7&_nc_sid..."
}
}
],
"cursor": null,
"has_more": false,
"parent": null
},
"cursor": null,
"has_more": false
}Fields
A page of results. Each entry in items is a Advertiser. cursor and has_more page through the rest.
A field the platform does not give is null, never made up. Extra platform details are in extra.
| Field | Type | Always | Notes |
|---|---|---|---|
object | "advertiser" | ||
platform | Platform | yes | the ad library's platform |
id | string or null | ||
name | string or null | ||
url | string or null | ||
page_id | string or null | ||
country | string or null | ||
verified | boolean or null | ||
ad_count | integer or null | ||
extra | object or null |
Full field list in the reference for this endpoint and the data models. Errors are listed under Errors.
Questions
Which errors can it return?
invalid_params (do not retry), not_found (do not retry). Account and platform errors from the errors list can also happen. A failure always costs 0 credits.
How do I get more than one page?
Send the same request with cursor set to the cursor you received, until has_more is false. Each page costs its own price. See pagination.
Is there an SDK call for it?
The preview Python client has client.facebook.ad_library_search_companies(...) and the TypeScript client client.facebook.adLibrarySearchCompanies(). Both return the same envelope as the HTTP API. The packages are not published yet; plain HTTP works today in any language.
Can an AI agent call it?
Yes. The MCP server reaches every built endpoint, with the same prices.