Facebook Ad Library Ad API. Send an ad link or ID.
Creatives, run dates, placements and EU reach. We handle the proxies, blocks and platform changes.
Facebook Ad Library Ad API at a glance
Returns one ad from Meta's public Ad Library by its link or Library ID: its creatives, the days it ran, where it ran and who ran it. Each creative has its headline, text, link, call to action, images and videos, and the advertiser comes with its Page's likes, category, badge and linked Instagram account. Ads shown in the EU or the UK add the payer, beneficiary, targeting and reach by country, age and gender. Political and social-issue ads add Meta's impression, reach and spend ranges, and a branded content ad names its creator.
GET /v1/facebook/ad
- 1 credit per request, $0.75–$1.97 per 1,000 requests
- 20 typed fields null when unknown
urlis all it needs, e.g.https://www.facebook.com/ads/library/?id=1448538159982118- 100 credits free when you sign up, no card, so you can build before you spend
Send one request. Get 20 fields back.
Copy the request in your language, or hand it to your agent. Sign up for an API key and your first 100 credits are free.
$ npm install socialtapurl = https://www.facebook.com/ads/library/?id=1448538159982118const params = new URLSearchParams({
url: "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=DE&id=1103375555695370&media_type=all",
});
const res = await fetch(`https://socialtap.dev/v1/facebook/ad?${params}`, {
headers: { "x-api-key": process.env.SOCIALTAP_API_KEY ?? "" },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
const { data, meta } = body;
console.log(data, meta.credits_charged);import os
import requests
res = requests.get(
"https://socialtap.dev/v1/facebook/ad",
params={"url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=DE&id=1103375555695370&media_type=all"},
headers={"x-api-key": os.environ["SOCIALTAP_API_KEY"]},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
data, meta = body["data"], body["meta"]
print(data, meta["credits_charged"])require "json"
require "net/http"
uri = URI("https://socialtap.dev/v1/facebook/ad")
uri.query = URI.encode_www_form('url' => 'https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=DE&id=1103375555695370&media_type=all')
req = Net::HTTP::Get.new(uri)
req["x-api-key"] = ENV.fetch("SOCIALTAP_API_KEY")
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(req) }
body = JSON.parse(res.body)
raise "#{body["error"]["code"]}: #{body["error"]["message"]}" unless res.is_a?(Net::HTTPSuccess)
pp body["data"]
puts body["meta"]["credits_charged"]<?php
$query = http_build_query([
'url' => 'https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=DE&id=1103375555695370&media_type=all',
]);
$ch = curl_init('https://socialtap.dev/v1/facebook/ad?' . $query);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['x-api-key: ' . getenv('SOCIALTAP_API_KEY')],
]);
$body = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) >= 400) {
throw new RuntimeException($body['error']['code'] . ': ' . $body['error']['message']);
}
print_r($body['data']);
echo $body['meta']['credits_charged'], PHP_EOL;package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"net/url"
"os"
)
func main() {
q := url.Values{}
q.Set("url", "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=DE&id=1103375555695370&media_type=all")
req, err := http.NewRequest("GET", "https://socialtap.dev/v1/facebook/ad?"+q.Encode(), nil)
if err != nil {
log.Fatal(err)
}
req.Header.Set("x-api-key", os.Getenv("SOCIALTAP_API_KEY"))
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
var body struct {
Data json.RawMessage `json:"data"`
Meta map[string]any `json:"meta"`
Error *struct {
Code string `json:"code"`
Message string `json:"message"`
} `json:"error"`
}
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
log.Fatal(err)
}
if body.Error != nil {
log.Fatalf("%s: %s", body.Error.Code, body.Error.Message)
}
fmt.Println(string(body.Data), body.Meta["credits_charged"])
}curl -G 'https://socialtap.dev/v1/facebook/ad' \
--data-urlencode 'url=https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=DE&id=1103375555695370&media_type=all' \
-H "x-api-key: $SOCIALTAP_API_KEY"{
"data": {
"advertiser": {
"avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/792344054_2357663855066869_6663139051388824991_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=100&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&…",
"display_name": "Esso",
"id": "124748157936817",
"is_verified": false,
"url": "https://www.facebook.com/EssoDeutschland",
"username": "EssoDeutschland"
},
"approximate_fields": [
"country_codes",
"first_shown_at"
],
"audience_size": null,
"country_codes": [
"DE"
],
"creatives": [
{
"body": "Tanken, Snacks oder einen Kaffee? Das alles und viel mehr erwartet dich bei Esso.",
"cta_text": "Learn More",
"link_description": null,
"link_url": "https://www.esso.de/de-de/damit-fahren-wir-besser?utm_source=facebook&utm_medium=paidsocial&utm_campaign=masterbrand_2026_2hy&utm_term=backcourt&utm_content=1x1",
"media": [
{
"alt_text": null,
"duration_ms": null,
"expires_at": "2026-10-25T18:00:00Z",
"height": null,
"thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/790643179_1059949036747222_1732898320488340543_n.jpg?_nc_cat=108&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&oe=F2A52380",
"type": "video",
"url": "https://video-atl3-1.xx.fbcdn.net/o1/v/t2/f2/m366/AQND9e-BMjtzqCZ0FbPblGYcGQ8j6vUBXYkHq85AodwUFgS3orA-sRXh9lT5UbtsmnSpwL_ot094eYeH8PrC-ESExk25IqvuuNNAuelnG27pCQ.mp4?_nc_cat=107&_nc_sid=SCRUBBED&_nc_ht=video-atl3-1.xx.fbcdn.net&_nc_ohc=SCRUBBED&efg=SCRUBBED&ccb=SCRUBBED&vs=SCRUBBE…",
"width": null
}
],
"title": "Kraftstoff fürs Auto. Energie für dich."
},
{
"body": "Tanken, Snacks oder einen Kaffee? Das alles und viel mehr erwartet dich bei Esso.",
"cta_text": "Learn More",
"link_description": null,
"link_url": "https://www.esso.de/de-de/damit-fahren-wir-besser?utm_source=facebook&utm_medium=paidsocial&utm_campaign=masterbrand_2026_2hy&utm_term=backcourt&utm_content=1x1",
"media": [
{
"alt_text": null,
"duration_ms": null,
"expires_at": "2026-10-25T18:00:00Z",
"height": null,
"thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/793483318_2138943053709897_6112027891760479229_n.jpg?_nc_cat=109&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&oe=F2A52380",
"type": "video",
"url": "https://video-atl3-1.xx.fbcdn.net/o1/v/t2/f2/m366/AQOafqMPVLeUIBX39JYn6sJ6wu5hquY_pveq5cGWgLn5xbkWjWgCf3pq3ti3P2iXiQZ-wnATW_Vp5elabdXMmVFrQaPqu88jW3VEEQj6J0hvaw.mp4?_nc_cat=103&_nc_sid=SCRUBBED&_nc_ht=video-atl3-1.xx.fbcdn.net&_nc_ohc=SCRUBBED&efg=SCRUBBED&ccb=SCRUBBED&vs=SCRUBBE…",
"width": null
}
],
"title": "Kraftstoff fürs Auto. Energie für dich."
}
],
"first_shown_at": "2026-09-07T07:00:00Z",
"id": "1103375555695370",
"impressions": null,
"is_active": true,
"is_political": false,
"languages": [],
"last_shown_at": null,
"paid_by": "Esso",
"platform": "facebook",
"platform_specific": {
"facebook": {
"advertiser_categories": [
"Energy Company"
],
"advertiser_instagram": null,
"advertiser_instagram_follower_count": null,
"advertiser_like_count": 73755,
"beneficiary": "Esso",
"collation_count": null,
"collation_id": null,
"cta_type": "learn_more",
"impression_shares": null,
"is_advertiser_deleted": false,
"is_removed": false,
"is_synthetic": false,
"link_caption": "esso.de",
"partner": null,
"removal_reasons": [],
"special_ad_categories": [],
"targeting": [
{
"age_max": 65,
"age_min": 18,
"genders": [],
"locations": [
{
"is_excluded": false,
"name": "Germany",
"type": "countries"
}
],
"reach": 4974088,
"reach_by_country": [
{
"ages": [
{
"age_range": "18-24",
"female": 175420,
"male": 326568,
"unknown": 9562
},
{
"age_range": "Unknown",
"female": 161,
"male": 238,
"unknown": 146
},
{
"age_range": "65+",
"female": 263221,
"male": 309061,
"unknown": 4425
}
],
"country_code": "DE"
}
],
"region": "eu"
}
]
}
},
"publisher_platforms": [
"facebook",
"instagram"
],
"reach": null,
"spend": null,
"type": "dynamic",
"unknown_fields": [
"languages"
],
"url": "https://www.facebook.com/ads/library/?id=1103375555695370"
},
"meta": {
"request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
"platform": "facebook",
"source": "api",
"is_cached": false,
"credits_charged": 1,
"latency_ms": 756,
"fetched_at": "2026-10-25T12:00:00Z",
"input": {
"kind": "ad",
"id": "1103375555695370",
"url": "https://www.facebook.com/ads/library/?id=1103375555695370"
},
"credits_remaining": 9999,
"client_request_id": null,
"warnings": []
}
}import { SocialTap } from "socialtap";
const client = new SocialTap(); // apiKey defaults to process.env.SOCIALTAP_API_KEY
const res = await client.facebook.ad.get({ url: "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=DE&id=1103375555695370&media_type=all" });
console.log(res.data);
console.log(res.credits.charged, res.meta.request_id);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;
public class Main {
public static void main(String[] args) throws Exception {
String query = "url=" + encode("https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=DE&id=1103375555695370&media_type=all");
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://socialtap.dev/v1/facebook/ad?" + query))
.header("x-api-key", System.getenv("SOCIALTAP_API_KEY"))
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
// An error is {"error": {"code", "message", ...}}; success is {data, meta}, meta.credits_charged its price.
if (response.statusCode() >= 400) throw new RuntimeException(response.body());
System.out.println(response.body());
}
static String encode(String value) {
return URLEncoder.encode(value, StandardCharsets.UTF_8);
}
}using System.Text.Json;
using var http = new HttpClient();
http.DefaultRequestHeaders.Add("x-api-key", Environment.GetEnvironmentVariable("SOCIALTAP_API_KEY"));
var query = string.Join("&",
"url=" + Uri.EscapeDataString("https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=DE&id=1103375555695370&media_type=all"));
var res = await http.GetAsync("https://socialtap.dev/v1/facebook/ad?" + query);
using var body = JsonDocument.Parse(await res.Content.ReadAsStringAsync());
if (!res.IsSuccessStatusCode)
{
var error = body.RootElement.GetProperty("error");
throw new Exception($"{error.GetProperty("code")}: {error.GetProperty("message")}");
}
Console.WriteLine(body.RootElement.GetProperty("data"));
Console.WriteLine(body.RootElement.GetProperty("meta").GetProperty("credits_charged"));// Cargo.toml: reqwest = { version = "0.12", features = ["blocking", "json"] }, serde_json = "1"
use std::env;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let res = reqwest::blocking::Client::new()
.get("https://socialtap.dev/v1/facebook/ad")
.query(&[("url", "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=DE&id=1103375555695370&media_type=all")])
.header("x-api-key", env::var("SOCIALTAP_API_KEY")?)
.send()?;
let ok = res.status().is_success();
let body: serde_json::Value = res.json()?;
if !ok {
return Err(format!("{}: {}", body["error"]["code"], body["error"]["message"]).into());
}
println!("{} {}", body["data"], body["meta"]["credits_charged"]);
Ok(())
}200 OK · GET https://socialtap.dev/v1/facebook/adLong arrays and strings are shortened here. Real responses are complete.Docs One schema on 4 platforms.
The response reference lists every field, its type and when it is null. See the full schema.
Null means unknown
A field Facebook Ad Library doesn't show is null, never zero or an empty string, so a real zero always means zero.
What it accepts
The ad's Meta Ad Library link (facebook.com/ads/library/?id=…), the official Ad Library API's ad_snapshot_url (facebook.com/ads/archive/render_ad/?id=…), or its Library ID.
Write one parser
Facebook Ad Library, TikTok Ad Library, Google Ads Transparency Center and LinkedIn Ad Library answer in these fields, so the code that reads one reads them all.
platformstring- Library owner's platform ID (facebook for Meta's library, tiktok, google, linkedin).
idstring- Library ad ID (string).
urlstring- Public library page of the ad.
advertiserobject- The advertising page, business or account.
paid_bystring- Disclosed payer ("Paid for by").
is_activeboolean- True while the ad is running.
first_shown_atstring- First delivery, RFC 3339 UTC (often date-only: see approximate_fields).
last_shown_atstring- Last delivery, RFC 3339 UTC; null while active.
Live data from 33 platforms.
What teams build with the Facebook Ad Library Ad API.
Enrich search results with an ad's disclosures
Audit an ad's EU reach and targeting
Track a competitor's creative and where it ran
Research political ad audiences
Good to know before you build.
- advertiser.id is the Page's own ID. Facebook's posts and comments name a Page by its profile ID: join them to an advertiser by username, not id.
- Run dates are whole days in US Pacific time, as Meta reports them, so approximate_fields lists them.
- Payer, beneficiary and audience disclosures exist only for ads shown in the EU or the UK (political and social-issue ads also name their payer), and are null or empty for other ads.
- Impression, reach and spend ranges exist only for political and social-issue ads, and are null for the rest.
- country_codes holds only the countries the EU and UK disclosures name, so an ad shown elsewhere too may have run in more (approximate_fields then lists it).
- languages is always empty and listed in unknown_fields, because the Ad Library doesn't show an ad's language.
1 credit per request. Failed requests are free.
Buy credits once and spend them on any endpoint, on any platform.
| Source | Price per successful request | Per 1,000 requests |
|---|---|---|
Platform API api | 1 credit | $0.75–$1.97 |
- Cache hits are free.
- Credits from packs and top-ups never expire.
- A monthly plan's credits are spent first, and what is left of them ends at each renewal.
- Prices exclude tax: sales tax is added at checkout where it applies.
- Outside the US, plans and packs are sold to businesses: checkout asks for your VAT, GST or other business tax ID.
Questions about the Facebook Ad Library Ad API.
More in the API reference.
Where do I find an ad's Library ID?
In the ad's Ad Library link (facebook.com/ads/library/?id=…) or under "Library ID" on its card. Every ad the Facebook Ad Library Search API returns carries it as id, and the official Ad Library API's ad_snapshot_url has it too.
Does it return ads that stopped running?
Yes. It returns any ad in Meta's public Ad Library, active or inactive, with is_active and the day it last ran.
How much does the Facebook Ad Library Ad API cost?
A request costs 1 credit. SocialTap credits cost $0.75–$1.97 per 1,000, depending on the plan or pack.
Try it on a link you already have.
Paste it in the playground, or copy the request into your code.
100free credits
- No credit card
- Failed requests are free
- Works on all 218 endpoints