How do I search Facebook ads by country via API?
Updated on · Sources
Pass country to GET /facebook/ads/search: an ISO code (US, BR, DE…) for the ads shown in that country, or ALL. GET /facebook/ads/countries lists the codes the Ad Library supports.
Meta's official option
Meta's Ad Library API filters by country too, but as of November 2026 its docs say ads that reached no EU location are returned only if they're about social issues, elections or politics. So commercial ads in the US, Brazil or India aren't in it.
How to do it with SocialAPIs
Combine country with query (keyword) or ad_page_id (one advertiser), activeStatus and after_time / before_time (YYYY-MM-DD). Each search costs 1 credit; the country list costs 1 credit.
To compare markets, run the same search once per country and diff the ad_archive_ids. The free Facebook Ad Checker tries one keyword or Page in one country in the browser.
Endpoints
GET /facebook/ads/search1 credit
Search ads in the Meta Ad Library by keyword or page ID with filters.
Params:
query,ad_page_id,country,activeStatus,after_time,before_time,sort_data,end_cursorMeta Ads Library Search: docs and playgroundMCP:
facebook_ads→searchGET /facebook/ads/countries1 credit
Get list of supported country codes for Meta Ads Library filtering.
Meta Ads Supported Countries: docs and playgroundMCP:
facebook_ads→countries
curl -G "https://api.socialapis.io/facebook/ads/search" \
--max-time 100 \
--fail-with-body \
-H "x-api-token: $SOCIALAPIS_API_KEY" \
--data-urlencode "query=running shoes" \
--data-urlencode "country=BR" \
--data-urlencode "activeStatus=Active"import os
import requests
response = requests.get(
"https://api.socialapis.io/facebook/ads/search",
headers={"x-api-token": os.environ["SOCIALAPIS_API_KEY"]},
params={
"query": "running shoes",
"country": "BR",
"activeStatus": "Active",
},
timeout=100,
)
response.raise_for_status()
print(response.json())// Node 18+, as an ES module (e.g. main.mjs)
async function get(url, params) {
const query = new URLSearchParams(params).toString();
const response = await fetch(query ? `${url}?${query}` : url, {
headers: { "x-api-token": process.env.SOCIALAPIS_API_KEY },
signal: AbortSignal.timeout(100000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
return response.json();
}
const data = await get("https://api.socialapis.io/facebook/ads/search", {
query: "running shoes",
country: "BR",
activeStatus: "Active",
});
console.log(data);import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.Map;
import java.util.stream.Collectors;
public class Main {
private static final HttpClient CLIENT = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(10))
.build();
public static void main(String[] args) throws Exception {
String body = get("https://api.socialapis.io/facebook/ads/search", Map.of(
"query", "running shoes",
"country", "BR",
"activeStatus", "Active"));
System.out.println(body);
}
static String get(String url, Map<String, String> params) throws Exception {
String query = params.entrySet().stream()
.map(e -> URLEncoder.encode(e.getKey(), StandardCharsets.UTF_8) + "="
+ URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8))
.collect(Collectors.joining("&"));
HttpRequest request = HttpRequest.newBuilder(URI.create(query.isEmpty() ? url : url + "?" + query))
.header("x-api-token", System.getenv("SOCIALAPIS_API_KEY"))
.timeout(Duration.ofSeconds(100))
.GET()
.build();
HttpResponse<String> response = CLIENT.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() / 100 != 2) {
throw new RuntimeException("HTTP " + response.statusCode() + ": " + response.body());
}
return response.body();
}
}package main
import (
"fmt"
"io"
"log"
"net/http"
"net/url"
"os"
"time"
)
func main() {
body, err := get("https://api.socialapis.io/facebook/ads/search", url.Values{
"query": {"running shoes"},
"country": {"BR"},
"activeStatus": {"Active"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(string(body))
}
func get(endpoint string, params url.Values) ([]byte, error) {
if len(params) > 0 {
endpoint += "?" + params.Encode()
}
req, err := http.NewRequest(http.MethodGet, endpoint, nil)
if err != nil {
return nil, err
}
req.Header.Set("x-api-token", os.Getenv("SOCIALAPIS_API_KEY"))
client := &http.Client{Timeout: 100 * time.Second}
resp, err := client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
return nil, err
}
if resp.StatusCode/100 != 2 {
return nil, fmt.Errorf("HTTP %d: %s", resp.StatusCode, body)
}
return body, nil
}# pip install socialapis-sdk
import os
from socialapis import Facebook
client = Facebook(api_token=os.environ["SOCIALAPIS_API_KEY"])
response = client.search_ads(
"running shoes",
country="BR",
activeStatus="Active",
)
print(response)// npm install socialapis-sdk
import { Facebook } from "socialapis-sdk";
const client = new Facebook({ apiToken: process.env.SOCIALAPIS_API_KEY });
const response = await client.searchAds("running shoes", {
country: "BR",
activeStatus: "Active",
});
console.log(response);Your API key goes in the x-api-token header (here from the SOCIALAPIS_API_KEY environment variable). Get a free key.
Tutorial: Facebook Ads Library API without app reviewUse it from Claude, ChatGPT or Cursor (MCP)
Good to know
- The country filter is where an ad was shown, not where the advertiser is based.
- Instagram ads are included, with
INSTAGRAMinpublisher_platform. spendstaysnullfor commercial ads in every country.
Sources
Checked on 2026-11-16.