SignalFacebook-Ad-Library · company/ads
List public Meta Ad Library ads for a Page. GET /api/v1/facebook-ad-library/company/ads accepts your x-api-key header. This endpoint returns live public data; demo mode is unavailable.
Request parameters
Searches the official Meta Ad Library API by Facebook Page ID. A company name is not an exact source identifier and is not supported. 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. Production remains blocked pending access approval and written paid-use clearance.
| Parameter | Type | Required | Description |
|---|---|---|---|
pageId | string | Yes | Numeric Facebook Page ID to find matching public ad archive records. |
companyName | string | No | Unsupported: use the exact numeric Facebook Page ID. |
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. |
ad_type | string | No | Archive ad type, subject to Meta’s geographic availability rules. Allowed: all, political_and_issue_ads. Default: all. |
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. |
language | string | No | ISO language code filter. |
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. |
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/company/ads?pageId=pageId" \
-H "x-api-key: $SIGNALSHELF_API_KEY"const response = await fetch(process.env.SIGNALSHELF_BASE_URL + "/api/v1/facebook-ad-library/company/ads?pageId=pageId", {
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/company/ads?pageId=pageId",
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.