Skip to content

How to search the Facebook Ad Library with an API

Updated · 3 steps

The Meta Ad Library shows every active ad running on Facebook and Instagram, but the website is built for browsing, not for tracking competitors over time. These three calls return the same data as JSON, with the Ad Library's own filters.

A typical workflow finds a brand's page id, pulls that page's ads, then searches by keyword to see who else advertises on the same terms.

01

Find the brand's page id

Search by company or page name. Each result carries its page_id, likes and linked Instagram account, so you can pick the right page when a brand has several.

cURL

curl --request GET 'https://api.fetchproof.com/v1/facebook/adLibrary/search/companies?query=Nike' \
  --header 'x-api-key: YOUR_API_KEY'

JavaScript

const response = await fetch("https://api.fetchproof.com/v1/facebook/adLibrary/search/companies?query=Nike", {
  method: 'GET',
  headers: {
    'x-api-key': process.env.FETCHPROOF_API_KEY,
  },
});
const data = await response.json();
console.log(data);

Python

import os
import requests

response = requests.get(
    "https://api.fetchproof.com/v1/facebook/adLibrary/search/companies?query=Nike",
    headers={"x-api-key": os.environ["FETCHPROOF_API_KEY"]},
)
print(response.json())

Go

package main

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

func main() {
  req, _ := http.NewRequest("GET", "https://api.fetchproof.com/v1/facebook/adLibrary/search/companies?query=Nike", nil)
  req.Header.Set("x-api-key", os.Getenv("FETCHPROOF_API_KEY"))
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init("https://api.fetchproof.com/v1/facebook/adLibrary/search/companies?query=Nike");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    'x-api-key: ' . getenv('FETCHPROOF_API_KEY'),
  ],
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Excerpt of published sample response Full response →
{
  "success": true,
  "credits_remaining": 100,
  "credits_charged": 1,
  "searchResults": [
    {
      "page_id": "15087023444",
      "category": "Sportswear Store",
      "image_uri": "https://scontent-iad6-1.xx.fbcdn.net/v/t39.30808-1/284964043_10159903868513445_76963539849…",
      "likes": 39489061,
      "verification": "BLUE_VERIFIED",
      "name": "Nike",
      "country": null,
      "entity_type": "PERSON_PROFILE",
      "ig_username": "nike",
      "ig_followers": 290769416,
      "ig_verification": true,
      "page_alias": "nike",
      "…": "1 more fields"
    }
  ]
}
02

Pull the page's ads

Pass the page_id as pageId. You can also pass companyName and skip step 1. It resolves to an exact name match first, otherwise to the top match.

Filter with country, status (active by default), media_type, language, and a start_date and end_date for impressions. Results come sorted by impressions unless you change sort_by. Each ad carries its copy, call to action, landing URL, start and end dates, and the platforms it ran on.

GET /v1/facebook/adLibrary/company/ads 1 credit per call

cURL

curl --request GET 'https://api.fetchproof.com/v1/facebook/adLibrary/company/ads?pageId=15087023444&country=US' \
  --header 'x-api-key: YOUR_API_KEY'

JavaScript

const response = await fetch("https://api.fetchproof.com/v1/facebook/adLibrary/company/ads?pageId=15087023444&country=US", {
  method: 'GET',
  headers: {
    'x-api-key': process.env.FETCHPROOF_API_KEY,
  },
});
const data = await response.json();
console.log(data);

Python

import os
import requests

response = requests.get(
    "https://api.fetchproof.com/v1/facebook/adLibrary/company/ads?pageId=15087023444&country=US",
    headers={"x-api-key": os.environ["FETCHPROOF_API_KEY"]},
)
print(response.json())

Go

package main

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

func main() {
  req, _ := http.NewRequest("GET", "https://api.fetchproof.com/v1/facebook/adLibrary/company/ads?pageId=15087023444&country=US", nil)
  req.Header.Set("x-api-key", os.Getenv("FETCHPROOF_API_KEY"))
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init("https://api.fetchproof.com/v1/facebook/adLibrary/company/ads?pageId=15087023444&country=US");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    'x-api-key: ' . getenv('FETCHPROOF_API_KEY'),
  ],
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Excerpt of published sample response Full response →
{
  "success": true,
  "credits_remaining": 100,
  "credits_charged": 1,
  "results": [
    {
      "ad_archive_id": "1702938977100376",
      "ad_id": null,
      "categories": [
        "UNKNOWN"
      ],
      "collation_count": null,
      "collation_id": null,
      "contains_digital_created_media": false,
      "contains_sensitive_content": false,
      "currency": "",
      "end_date": 1794902400,
      "fev_info": null,
      "gated_type": "ELIGIBLE",
      "has_user_reported": false,
      "…": "21 more fields"
    }
  ],
  "cursor": "eyJuIjoyLCJzIjpudWxsLCJ1IjoiMDUyZWFkMTktM2ZlZC00OGVhLWJiNzEtOTdmZDdkYzQ4NzQ3IiwiYyI6IkFRSF…"
}
03

Search every advertiser by keyword

To see who advertises on a term, search all ads by keyword. search_type=keyword_exact_phrase matches the phrase exactly as written. ad_type limits results to political and issue ads.

GET /v1/facebook/adLibrary/search/ads 1 credit per call

cURL

curl --request GET 'https://api.fetchproof.com/v1/facebook/adLibrary/search/ads?query=running+shoes&country=US' \
  --header 'x-api-key: YOUR_API_KEY'

JavaScript

const response = await fetch("https://api.fetchproof.com/v1/facebook/adLibrary/search/ads?query=running+shoes&country=US", {
  method: 'GET',
  headers: {
    'x-api-key': process.env.FETCHPROOF_API_KEY,
  },
});
const data = await response.json();
console.log(data);

Python

import os
import requests

response = requests.get(
    "https://api.fetchproof.com/v1/facebook/adLibrary/search/ads?query=running+shoes&country=US",
    headers={"x-api-key": os.environ["FETCHPROOF_API_KEY"]},
)
print(response.json())

Go

package main

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

func main() {
  req, _ := http.NewRequest("GET", "https://api.fetchproof.com/v1/facebook/adLibrary/search/ads?query=running+shoes&country=US", nil)
  req.Header.Set("x-api-key", os.Getenv("FETCHPROOF_API_KEY"))
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init("https://api.fetchproof.com/v1/facebook/adLibrary/search/ads?query=running+shoes&country=US");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    'x-api-key: ' . getenv('FETCHPROOF_API_KEY'),
  ],
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Excerpt of published sample response Full response →
{
  "success": true,
  "credits_remaining": 100,
  "credits_charged": 1,
  "searchResults": [
    {
      "ad_archive_id": "953573607005202",
      "ad_id": null,
      "categories": [
        "UNKNOWN"
      ],
      "collation_count": null,
      "collation_id": null,
      "contains_digital_created_media": false,
      "contains_sensitive_content": false,
      "currency": "",
      "end_date": 1794816000,
      "fev_info": null,
      "gated_type": "ELIGIBLE",
      "has_user_reported": false,
      "…": "21 more fields"
    }
  ],
  "searchResultsCount": 50001,
  "cursor": "eyJuIjoyLCJzIjpudWxsLCJ1IjoiYTMwMWFjMzktNjYzOC00ZDg5LTlhNDUtYTcxM2FhYjI1YmExIiwiYyI6IkFRSF…"
}

Paging and cost

Each page of results costs 1 credit and returns a cursor. Send it with the same filters to get the next page. An empty page costs 0 credits, and an unknown companyName returns a 404 at 0 credits.

Country filter

country is where Facebook showed the ad, not where the advertiser is based. Results can include foreign advertisers whose ads reached that country.

Try it with 100 free credits

Sign up with an email address, no card. Credits never expire. Errors cost 0 credits, and each endpoint page lists exactly what it charges.