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.
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; {
"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"
}
]
} 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.
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; {
"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…"
} 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.
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; {
"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.