SignalFacebook-Ad-Library · search
Search public ads in Meta Ad Library. GET /api/v1/facebook-ad-library/search accepts your x-api-key header. This endpoint returns live public data; demo mode is unavailable.
Request parameters
Uses Meta’s official Ad Library API. Political/issue ads can be queried globally for up to seven years. Ads of any type are available only for the UK and EU, for up to one year. Identity/location verification and an approved Meta developer app are required. This partial adapter omits transcript extraction, unsupported sort modes, and fields Meta does not return. Production remains blocked pending access approval, retention review, and written paid-use clearance.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Search phrase (Meta limit: 100 characters). |
sort_by | string | No | Accepted for reference compatibility but rejected: Meta does not document an equivalent sort mode for this adapter. Allowed: total_impressions, relevancy_monthly_grouped. |
search_type | string | No | Match all query terms or the exact phrase. Allowed: keyword_unordered, keyword_exact_phrase. Default: keyword_unordered. |
ad_type | string | No | Archive ad type, subject to Meta’s geographic availability rules. Allowed: all, political_and_issue_ads. Default: all. |
country | string | No | Country where an ad reached viewers. Commercial ads are available through this API only for the UK and EU; political/issue ads have broader country coverage. |
language | string | No | ISO language code filter. |
status | string | No | Meta ad delivery status filter. Allowed: ALL, ACTIVE, INACTIVE. Default: ALL. |
media_type | string | No | Meta creative media type filter. Allowed: ALL, IMAGE, VIDEO, MEME, IMAGE_AND_MEME, NONE. Default: ALL. |
start_date | string | No | Inclusive date in YYYY-MM-DD form. Maximum archive window is one year for all ads and seven years for political/issue ads. |
end_date | string | No | Inclusive date in YYYY-MM-DD form. Maximum archive window is one year for all ads and seven years for political/issue ads. |
trim | boolean | No | Accepted for compatibility; output remains a fixed source-field allowlist. |
cursor | string | No | Opaque Meta Graph cursor from the previous page. |
freshness | string | No | 24h (default), 1h, 7d, or live. Accepted cache hits are free; live forces refresh except simultaneous requests may share newly fetched data. |
Code examples
Set SIGNALSHELF_BASE_URL and SIGNALSHELF_API_KEY on your server.
curl "$SIGNALSHELF_BASE_URL/api/v1/facebook-ad-library/search?query=query" \
-H "x-api-key: $SIGNALSHELF_API_KEY"const response = await fetch(process.env.SIGNALSHELF_BASE_URL + "/api/v1/facebook-ad-library/search?query=query", {
headers: { 'x-api-key': process.env.SIGNALSHELF_API_KEY },
});
const body = await response.json();
if (!response.ok) throw new Error(body.error.message);
console.log(body.data, body.meta);import os, requests
response = requests.get(
os.environ['SIGNALSHELF_BASE_URL'] + "/api/v1/facebook-ad-library/search?query=query",
headers={'x-api-key': os.environ['SIGNALSHELF_API_KEY']},
timeout=30,
)
response.raise_for_status()
print(response.json())Response and pagination
The response contains data and meta. data includes platform, resource, sample:false, provider, and the public source payload. Lists return data.items; individual resources return data.data.
Author feeds include data.next_cursor. Return it unchanged in cursor for the next page. Feed entries can include reposts. Single-post lookups resolve the handle to a DID first. Deleted or moderated posts may be unavailable.
meta includes event_id, mode, cache, credits_charged, fetched_at, age_seconds, and duration_ms. A fresh successful result costs one credit; accepted cached results and failures cost zero.
Availability and failures
Implementation is not a continuous availability guarantee. Source rate limits, retention, deleted content, restrictions, and regional availability apply. This is an independent SignalShelf contract, not a drop-in competitor response format.
400: invalid parameters. 401: missing/revoked key. 402: insufficient credits. 404: missing public resource. 429: SignalShelf throttle. 502/503: upstream failure or rate limit, with credit restored.