Skip to content
truescrape
Free key

Contents

Site

Facebook Ad Library Advertisers API

Open in ChatGPTOpen in ClaudeOpen in Gemini

Distinct advertisers whose ads match a search term, with the page_id needed by /v1/facebook/ad-library/page-ads. Derived from the ads an Ad Library search returns, ranked by how many of them each advertiser ran. Calls cost 1 credit each. A cache hit is free, and a failed or empty response is never charged.

Try it

Prefilled with the request that produced the example below. No key yet? Get a free key.

Request

GET/v1/facebook/ad-library/advertisers
ParameterTypeRequiredDescription
querystringyesAdvertiser name or a term from their ad copy
countrystringnodefaults to US
statusactive | inactive | allnodefaults to active
limitnumbernoAds sampled, 1-100. More ads means more advertisers.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/ad-library/advertisers?query=nike&cache_max_age=7d" \
  -H "x-api-key: $KEY"
JavaScript
const query = new URLSearchParams({
  query: 'nike',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/ad-library/advertisers?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/ad-library/advertisers",
    params={
        "query": "nike",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])

Example response

Captured on , with raw removed and lists cut to two items. A live call returns current data.

response
{
  "success": true,
  "data": {
    "items": [
      {
        "platform": "facebook",
        "id": "112727500143177",
        "handle": "RealWhatnot",
        "displayName": "Whatnot",
        "bio": null,
        "avatarUrl": "https://scontent-bcn1-1.xx.fbcdn.net/v/t39.35426-6/698958737_1001369008896162_251496731638715175_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=108&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=yOHvXc4jDgwQ7kNvwGxQFxk&_nc_oc=AdqvXiiLDonT-shDbbiunZyo3cTG-SmGoFSUvmHvxMhzW29UdolX3eRUHnaRHeUn17s&_nc_zt=14&_nc_ht=scontent-bcn1-1.xx&_nc_gid=Liw6EHJV1sD-ZLkE9iwovA&_nc_ss=7b289&oh=00_AQPCOyGZH5EZEjagFlFW454Uv2qrJSTTfyDJJenTZhucJg&oe=6ADDD1D9",
        "bannerUrl": null,
        "url": "https://www.facebook.com/ads/library/?view_all_page_id=112727500143177&search_type=page",
        "verified": null,
        "followerCount": null,
        "followingCount": null,
        "postCount": null,
        "viewCount": null,
        "isPrivate": null,
        "isBusiness": true,
        "category": "Shopping",
        "location": null,
        "externalLinks": [],
        "createdAt": null,
        "fetchedAt": "2026-10-21T01:51:14.676Z"
      },
      {
        "platform": "facebook",
        "id": "156405867784232",
        "handle": "depop",
        "displayName": "Depop",
        "bio": null,
        "avatarUrl": "https://scontent-bcn1-1.xx.fbcdn.net/v/t39.35426-6/706217505_1282327247074242_6940108535499458481_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=105&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=FqRZbC76izIQ7kNvwFypzo3&_nc_oc=AdoXWVxUCptf3h5CfgP7RtkuXA6hYjiDhPkk0AOv4wSoFyHQj5KvHzSRK7nojPwcwfc&_nc_zt=14&_nc_ht=scontent-bcn1-1.xx&_nc_gid=Liw6EHJV1sD-ZLkE9iwovA&_nc_ss=7b289&oh=00_AQMb6NKEbpl22vVmXUpbogud41ZI6KtKUSEhEjSGx_EtsQ&oe=6ADDE235",
        "bannerUrl": null,
        "url": "https://www.facebook.com/ads/library/?view_all_page_id=156405867784232&search_type=page",
        "verified": null,
        "followerCount": null,
        "followingCount": null,
        "postCount": null,
        "viewCount": null,
        "isPrivate": null,
        "isBusiness": true,
        "category": "Shopping",
        "location": null,
        "externalLinks": [],
        "createdAt": null,
        "fetchedAt": "2026-10-21T01:51:14.676Z"
      }
    ]
  },
  "meta": {
    "platform": "facebook",
    "endpoint": "facebook.adLibraryAdvertisers",
    "creditsCharged": 1,
    "cached": false,
    "cacheAgeSeconds": null,
    "durationMs": 11166,
    "requestId": "req_doqfk9hkg7c7bvl1hxd3"
  }
}

Returns

Returns a list of Creator in data.items.

Cost and behaviour

Credits1 per live request, 0 on a cache hit
Cacheableyes: cache_max_age accepts a cached copy
Batchableyes: usable as a target in POST /v1/jobs/batch
Subscribableno

Other Facebook endpoints

All Facebook endpointsThe unified schema