Facebook Ad Library Search API
curl --request POST \
--url https://api.socq.ai/v1/facebook-ad-library/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "<string>",
"ad_type": "<string>",
"country": "<string>",
"end_date": "<string>",
"media_type": "<string>",
"results_limit": 1000,
"search_type": "<string>",
"sort_by": "<string>",
"start_date": "<string>",
"status": "<string>"
}
'import requests
url = "https://api.socq.ai/v1/facebook-ad-library/search"
payload = {
"query": "<string>",
"ad_type": "<string>",
"country": "<string>",
"end_date": "<string>",
"media_type": "<string>",
"results_limit": 1000,
"search_type": "<string>",
"sort_by": "<string>",
"start_date": "<string>",
"status": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: '<string>',
ad_type: '<string>',
country: '<string>',
end_date: '<string>',
media_type: '<string>',
results_limit: 1000,
search_type: '<string>',
sort_by: '<string>',
start_date: '<string>',
status: '<string>'
})
};
fetch('https://api.socq.ai/v1/facebook-ad-library/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://api.socq.ai/v1/facebook-ad-library/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => '<string>',
'ad_type' => '<string>',
'country' => '<string>',
'end_date' => '<string>',
'media_type' => '<string>',
'results_limit' => 1000,
'search_type' => '<string>',
'sort_by' => '<string>',
'start_date' => '<string>',
'status' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.socq.ai/v1/facebook-ad-library/search"
payload := strings.NewReader("{\n \"query\": \"<string>\",\n \"ad_type\": \"<string>\",\n \"country\": \"<string>\",\n \"end_date\": \"<string>\",\n \"media_type\": \"<string>\",\n \"results_limit\": 1000,\n \"search_type\": \"<string>\",\n \"sort_by\": \"<string>\",\n \"start_date\": \"<string>\",\n \"status\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.socq.ai/v1/facebook-ad-library/search")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"<string>\",\n \"ad_type\": \"<string>\",\n \"country\": \"<string>\",\n \"end_date\": \"<string>\",\n \"media_type\": \"<string>\",\n \"results_limit\": 1000,\n \"search_type\": \"<string>\",\n \"sort_by\": \"<string>\",\n \"start_date\": \"<string>\",\n \"status\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.socq.ai/v1/facebook-ad-library/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"<string>\",\n \"ad_type\": \"<string>\",\n \"country\": \"<string>\",\n \"end_date\": \"<string>\",\n \"media_type\": \"<string>\",\n \"results_limit\": 1000,\n \"search_type\": \"<string>\",\n \"sort_by\": \"<string>\",\n \"start_date\": \"<string>\",\n \"status\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"code": 200,
"data": {
"task_id": "<string>",
"status": "<string>",
"created_time": "<string>"
}
}{
"code": 422,
"error": {
"message": "<string>",
"type": "<string>",
"details": {}
}
}Ad Library Search
Search public Facebook Ad Library ads by keyword.
POST
/
v1
/
facebook-ad-library
/
search
Facebook Ad Library Search API
curl --request POST \
--url https://api.socq.ai/v1/facebook-ad-library/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "<string>",
"ad_type": "<string>",
"country": "<string>",
"end_date": "<string>",
"media_type": "<string>",
"results_limit": 1000,
"search_type": "<string>",
"sort_by": "<string>",
"start_date": "<string>",
"status": "<string>"
}
'import requests
url = "https://api.socq.ai/v1/facebook-ad-library/search"
payload = {
"query": "<string>",
"ad_type": "<string>",
"country": "<string>",
"end_date": "<string>",
"media_type": "<string>",
"results_limit": 1000,
"search_type": "<string>",
"sort_by": "<string>",
"start_date": "<string>",
"status": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: '<string>',
ad_type: '<string>',
country: '<string>',
end_date: '<string>',
media_type: '<string>',
results_limit: 1000,
search_type: '<string>',
sort_by: '<string>',
start_date: '<string>',
status: '<string>'
})
};
fetch('https://api.socq.ai/v1/facebook-ad-library/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://api.socq.ai/v1/facebook-ad-library/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => '<string>',
'ad_type' => '<string>',
'country' => '<string>',
'end_date' => '<string>',
'media_type' => '<string>',
'results_limit' => 1000,
'search_type' => '<string>',
'sort_by' => '<string>',
'start_date' => '<string>',
'status' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.socq.ai/v1/facebook-ad-library/search"
payload := strings.NewReader("{\n \"query\": \"<string>\",\n \"ad_type\": \"<string>\",\n \"country\": \"<string>\",\n \"end_date\": \"<string>\",\n \"media_type\": \"<string>\",\n \"results_limit\": 1000,\n \"search_type\": \"<string>\",\n \"sort_by\": \"<string>\",\n \"start_date\": \"<string>\",\n \"status\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.socq.ai/v1/facebook-ad-library/search")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"<string>\",\n \"ad_type\": \"<string>\",\n \"country\": \"<string>\",\n \"end_date\": \"<string>\",\n \"media_type\": \"<string>\",\n \"results_limit\": 1000,\n \"search_type\": \"<string>\",\n \"sort_by\": \"<string>\",\n \"start_date\": \"<string>\",\n \"status\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.socq.ai/v1/facebook-ad-library/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"<string>\",\n \"ad_type\": \"<string>\",\n \"country\": \"<string>\",\n \"end_date\": \"<string>\",\n \"media_type\": \"<string>\",\n \"results_limit\": 1000,\n \"search_type\": \"<string>\",\n \"sort_by\": \"<string>\",\n \"start_date\": \"<string>\",\n \"status\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"code": 200,
"data": {
"task_id": "<string>",
"status": "<string>",
"created_time": "<string>"
}
}{
"code": 422,
"error": {
"message": "<string>",
"type": "<string>",
"details": {}
}
}Ad Library Search
Search public ads by keyword, status, country, media type, and date range.Request Example
{
"query": "running shoes",
"results_limit": 100,
"country": "US",
"status": "ACTIVE",
"media_type": "VIDEO",
"sort_by": "total_impressions"
}
Use with MCP
| Interface | Value |
|---|---|
| REST | POST /v1/facebook-ad-library/search |
| Compact MCP | socq_execute with endpoint: "facebook-ad-library/search" |
| Typed MCP | socq_facebook_ad_library_search |
| Exact-tool URL | https://api.socq.ai/mcp?tools=facebook_ad_library_search |
| CLI | socq facebook-ad-library search |
input object for socq_execute, or pass the same fields directly to the typed tool. Typed tools also accept _wait_seconds, _result_limit, and _idempotency_key.
A successful collection returns a
task_id. Continue with socq_get_task until the task succeeds, then read normalized records from results.items.results_limit is reached, no next page is available, or the task reaches its pagination safety boundary. Duplicate ad IDs are saved once.
Result Fields
Task results use the stable SocQ fields below. Source-specific field names and formats are normalized without inferring or enriching values that the source did not provide. To request a smaller field set, usefields for MCP queries, _result_fields for typed tools, or --result-fields in the CLI. Declared fields remain present when their value is null.
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | Yes | Unique identifier for this result item. |
platform | string | No | Platform the result belongs to, such as instagram or linkedin. |
resource | string | No | SocQ resource represented by the result, such as videos or comments. |
type | string | No | Category of the result item, such as video, post, or comment. |
url | string | Yes | Public URL of the result item when available. |
published_at | string | Yes | Time the source item was published, in ISO 8601 format when available. |
collected_at | string | No | Time SocQ collected or processed this result, in ISO 8601 format. |
text | string | Yes | Advertising copy or creative text. |
advertiser | object | Yes | Advertiser responsible for the ad. |
advertiser.id | string | Yes | Unique identifier of the advertiser. |
advertiser.name | string | Yes | Display name of the advertiser. |
advertiser.url | string | Yes | Public URL of the advertiser when available. |
advertiser.logo_url | string | Yes | URL of the company or advertiser logo. |
start_date | string | Yes | Date the ad started running when available. |
end_date | string | Yes | Date the ad stopped running when available. |
countries | array<string> | Yes | Countries or regions where the ad was delivered. |
platforms | array<string> | Yes | Placements or platforms where the ad was delivered. |
format | string | Yes | Advertising creative format, such as image or video. |
landing_page_url | string | Yes | Destination URL opened from the ad. |
impressions | integer | Yes | Number of ad impressions when reported. |
media | array<object> | Yes | Images, videos, or other media attached to the result. |
media.type | string | Yes | Media kind, such as image or video. |
media.url | string | Yes | URL of the media asset. |
media.thumbnail_url | string | Yes | URL of the media preview image. |
media.width | integer | Yes | Media width in pixels. |
media.height | integer | Yes | Media height in pixels. |
media.duration_seconds | number | Yes | Media duration in seconds. |
Completed Task Response
{
"code": 200,
"data": {
"task_id": "A1B2C3D4E5F6G7H8",
"status": "succeeded",
"public_id": "facebook-ad-library/search",
"result_count": 1,
"credits_amount": 0.5,
"results": {
"limit": 50,
"next_cursor": null,
"has_more": false,
"schema_id": "ad",
"schema_version": "1.0",
"items": [
{
"id": "615470338018648",
"platform": "facebook-ad-library",
"resource": "search",
"type": "ad",
"url": "https://www.facebook.com/ads/library/?id=615470338018648",
"published_at": "2026-07-01T00:00:00Z",
"collected_at": "2026-07-18T10:30:00Z",
"text": "Lightweight running shoes for everyday training.",
"advertiser": {
"id": "115531458627129",
"name": "Example Sports",
"url": null,
"logo_url": null
},
"start_date": null,
"end_date": null,
"countries": null,
"platforms": null,
"format": null,
"landing_page_url": null,
"impressions": null,
"media": [
{
"type": "video",
"url": "https://example.com/ad.mp4",
"thumbnail_url": null,
"width": null,
"height": null,
"duration_seconds": null
}
]
}
]
}
}
}
Authorizations
bearerAuthapiKeyAuth
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Search query.
Minimum string length:
1Minimum string length:
1Minimum string length:
1Minimum string length:
1Minimum string length:
1Required range:
1 <= x <= 2000Minimum string length:
1Minimum string length:
1Minimum string length:
1Minimum string length:
1
