facebook_ad_library_company_ads
Ads for one Meta page — active by default, Meta's top-by-impressions order, sort_by and date window, same envelope as /facebook/search. Each ad has creativeHash + landingDomain; dedupe=true merges repeats. Costs 2 credits. Empty results and failures are never charged. Pass cache=true for a free 24h cache hit (default always fresh).
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"url": "<url>"
},
"name": "facebook_ad_library_company_ads"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | pageId from /search-companies (preferred), libraryUrl, vanity page URL (facebook.com/nike/), or Ad Library URL with view_all_page_id. Do not pass profileId from facebook.com/{digits}/ when it differs from pageId. The URL platform must match this endpoint's platform. Do not pass cross-platform URLs, e.g. YouTube to TikTok, Instagram to Facebook, LinkedIn to X/Twitter, or Pinterest to Rumble. | |
| cache | No | Set true to serve from the 24h response cache (0 credits on hit). Default false — always fetch fresh. | |
| limit | No | Max items to return (default 20, max 200). Flat 2 credits per call on the native path; the extended fallback bills per returned ad. | |
| cursor | No | Pagination cursor from a previous nextCursor. Pages through the current Meta HTML result batch. | |
| dedupe | No | When true, ads with the same creativeHash (same copy, headline and landing domain) collapse into one row, the first in library order, with duplicateIds[] (every ad id in the group) and duplicateCount (group size). Duplicates are merged only among the ads this request fetched (retrievableCount). Ads from another request or from library pages past this batch are not compared, so the same creative can appear again there. Default false: every ad is its own row and no duplicate fields are added. Same price. | |
| fields | No | Optional comma-separated keys to keep on each result row (or on the object for single-item tools), e.g. id,url,publishedAt,engagement. Pagination keys are always kept. Does not change the price. | |
| status | No | Ad delivery status: ACTIVE (default), INACTIVE, or ALL. Use ACTIVE for "what are they running now?". | |
| compact | No | Default true here: drop signed media URLs (video, image, avatar links and their expiry stamps) to keep the response small. Ids, permalinks, dates, text and metrics stay. On Threads, Facebook, Meta Ad Library and TikTok Shop tools request timings are dropped too. Pass false for the full body. | |
| country | No | Two-letter ISO country code, or ALL for every country (Meta's own value). Default US. For inactive ads prefer ALL: a single-country search can list far fewer inactive ads than ALL. Other non-ISO codes are a definitive 400 INVALID_COUNTRY. | |
| sort_by | No | Meta sort mode: total_impressions or relevancy_monthly_grouped. Omit for Meta's default ranking (top ads by impressions first). | |
| end_date | No | Only ads shown (delivered) on or before this date (YYYY-MM-DD). | |
| start_date | No | Only ads shown (delivered) on or after this date (YYYY-MM-DD). Delivery-date window, not a start-date filter: an ad that started earlier but was still running in the range is included. |