Ad Library Pages

curl --request GET \
  --url https://scrapebadger.com/v1/facebook/ads/pages/search \
  --header 'X-API-Key: <x-api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<x-api-key>'}};

fetch('https://scrapebadger.com/v1/facebook/ads/pages/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://scrapebadger.com/v1/facebook/ads/pages/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://scrapebadger.com/v1/facebook/ads/pages/search"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<x-api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://scrapebadger.com/v1/facebook/ads/pages/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<x-api-key>'

response = http.request(request)
puts response.read_body

{
  "pages": [
    {}
  ],
  "keyword_suggestions": [
    "<string>"
  ],
  "count": 123,
  "query": "<string>",
  "page_id": "<string>",
  "page_name": "<string>",
  "page_alias": "<string>",
  "page_category": "<string>",
  "entity_type": "<string>",
  "likes": 123,
  "verification": "<string>",
  "profile_photo": "<string>",
  "about": "<string>",
  "page_is_deleted": true,
  "hidden_ads": true,
  "ig_username": "<string>",
  "ig_followers": 123,
  "ig_verification": true,
  "page_creation_utc": 123,
  "page_created_at": "<string>",
  "owner": {},
  "admin_country_counts": [
    {}
  ],
  "history": [
    {}
  ],
  "state_media_country_label": "<string>",
  "related_pages": [
    {}
  ],
  "ad_spend": {}
}

GET

facebook

ads

pages

Ad Library Pages

curl --request GET \
  --url https://scrapebadger.com/v1/facebook/ads/pages/search \
  --header 'X-API-Key: <x-api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<x-api-key>'}};

fetch('https://scrapebadger.com/v1/facebook/ads/pages/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://scrapebadger.com/v1/facebook/ads/pages/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://scrapebadger.com/v1/facebook/ads/pages/search"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<x-api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://scrapebadger.com/v1/facebook/ads/pages/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<x-api-key>'

response = http.request(request)
puts response.read_body

{
  "pages": [
    {}
  ],
  "keyword_suggestions": [
    "<string>"
  ],
  "count": 123,
  "query": "<string>",
  "page_id": "<string>",
  "page_name": "<string>",
  "page_alias": "<string>",
  "page_category": "<string>",
  "entity_type": "<string>",
  "likes": 123,
  "verification": "<string>",
  "profile_photo": "<string>",
  "about": "<string>",
  "page_is_deleted": true,
  "hidden_ads": true,
  "ig_username": "<string>",
  "ig_followers": 123,
  "ig_verification": true,
  "page_creation_utc": 123,
  "page_created_at": "<string>",
  "owner": {},
  "admin_country_counts": [
    {}
  ],
  "history": [
    {}
  ],
  "state_media_country_label": "<string>",
  "related_pages": [
    {}
  ],
  "ad_spend": {}
}

Search for advertiser Pages in Facebook’s Ad Library (the same typeahead the Library UI uses), then pull a Page’s full transparency profile — ownership, admin country breakdown, creation/rename history, related Pages and, for political/issue advertisers, ad spend.

Endpoint	Returns
`GET /v1/facebook/ads/pages/search`	advertiser Page typeahead search
`GET /v1/facebook/ads/pages/{page_id}`	one Page’s info, transparency and ad spend

Credits: 5 (each)

Authorization

string

required

Your ScrapeBadger API key.

Query Parameters — `/ads/pages/search`

string

required

Advertiser name to search for.

string

default:"US"

ISO 3166-1 alpha-2 country code. The Ad Library is partitioned by country.

Path Parameters — `/ads/pages/{page_id}`

string

required

The numeric Page id, as returned in page_id on any search result.

string

default:"US"

ISO 3166-1 alpha-2 country code.

Response — `/ads/pages/search`

AdLibraryPageResult[]

Each result includes page_id, name, page_alias, category, likes, verification (e.g. BLUE_VERIFIED), entity_type (e.g. PERSON_PROFILE), country, ig_username, ig_followers, ig_verification, image_uri and page_is_deleted.

string[]

Related search keywords the Ad Library suggests for the query.

integer

Number of pages returned.

string

Echoes the query.

Response — `/ads/pages/{page_id}`

string

Numeric Page id.

string

Page display name.

string

Vanity handle (e.g. nike).

string

Facebook Page category.

string

Ad Library entity type.

integer

Page like count.

string

Verification badge, e.g. BLUE_VERIFIED.

string

Profile photo URL.

string

The Page’s about blurb.

boolean

Whether the Page has been deleted.

boolean

Whether the Page has ads hidden from the Library.

string

Linked Instagram username.

integer

Instagram follower count.

boolean

Whether the Instagram account is verified.

float

Page creation time, Unix seconds.

string

Page creation time, ISO 8601.

object

Confirmed Page owner: id, name, phone_number and address (city, state, postal_code, country).

object[]

Where the Page’s admins are located — {country, country_id, count} per country.

object[]

Page transparency history — {item_type, event_time_utc, event_at} where item_type is CREATION or NAME_CHANGE.

string

State-controlled-media label, if Facebook applies one.

Pages the Library links to this one — {page_id, page_name, country, country_name, category_name, page_verification, profile_image_uri}.

object

Political/issue ad spend: current_week, lifetime_by_disclaimer[] and weekly_by_disclaimer[]. Populated only for political/issue advertisers — commercial advertisers return empty spend.

Example

curl "https://scrapebadger.com/v1/facebook/ads/pages/search?query=Nike&country=US" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://scrapebadger.com/v1/facebook/ads/pages/15087023444?country=US" \
  -H "X-API-Key: YOUR_API_KEY"

const res = await fetch(
  "https://scrapebadger.com/v1/facebook/ads/pages/15087023444?country=US",
  { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } },
);
const page = await res.json();

import requests

res = requests.get(
    "https://scrapebadger.com/v1/facebook/ads/pages/15087023444",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"country": "US"},
)
page = res.json()

Response

{
  "page_id": "15087023444",
  "page_name": "Nike",
  "page_alias": "nike",
  "page_category": "Sportswear Store",
  "entity_type": "BUSINESS",
  "likes": 39571076,
  "verification": "BLUE_VERIFIED",
  "profile_photo": "https://scontent.xx.fbcdn.net/v/t39.30808-1/nike_profile.jpg",
  "about": "Just Do It.",
  "page_is_deleted": false,
  "hidden_ads": false,
  "ig_username": "nike",
  "ig_followers": 302514886,
  "ig_verification": true,
  "page_creation_utc": 1211328000.0,
  "page_created_at": "2008-05-21T00:00:00Z",
  "owner": {
    "id": "115941125123456",
    "name": "NIKE, Inc.",
    "phone_number": "+1 503-671-6453",
    "address": {
      "city": "Beaverton",
      "state": "OR",
      "postal_code": "97005",
      "country": "US"
    }
  },
  "admin_country_counts": [
    { "country": "United States", "country_id": "US", "count": 105 },
    { "country": "India", "country_id": "IN", "count": 31 }
  ],
  "history": [
    { "item_type": "CREATION", "event_time_utc": 1211328000.0, "event_at": "2008-05-21T00:00:00Z" },
    { "item_type": "NAME_CHANGE", "event_time_utc": 1367539200.0, "event_at": "2013-05-03T00:00:00Z" }
  ],
  "state_media_country_label": null,
  "related_pages": [
    {
      "page_id": "24714361749",
      "page_name": "Nike Football",
      "country": "US",
      "country_name": "United States",
      "category_name": "Sportswear Store",
      "page_verification": "BLUE_VERIFIED",
      "profile_image_uri": "https://scontent.xx.fbcdn.net/v/t39.30808-1/nike_football.jpg"
    }
  ],
  "ad_spend": {
    "current_week": null,
    "lifetime_by_disclaimer": [],
    "weekly_by_disclaimer": []
  }
}

ad_spend is populated only for political and issue advertisers — Facebook publishes spend for those, but not for commercial Pages like Nike, which return empty spend. Pair /ads/pages/search with /ads/search to go from an advertiser name to their full creative inventory.

Facebook API

Endpoints

Ad Library Pages

Authorization

Query Parameters — `/ads/pages/search`

Path Parameters — `/ads/pages/{page_id}`

Response — `/ads/pages/search`

Response — `/ads/pages/{page_id}`

Example

​Authorization

​Query Parameters — /ads/pages/search

​Path Parameters — /ads/pages/{page_id}

​Response — /ads/pages/search

​Response — /ads/pages/{page_id}

​Example

Authorization

Query Parameters — `/ads/pages/search`

Path Parameters — `/ads/pages/{page_id}`

Response — `/ads/pages/search`

Response — `/ads/pages/{page_id}`

Example