{"openapi":"3.1.0","info":{"title":"ApiToll — Facebook Ad Library + ad intelligence for AI agents","description":"ApiToll runs pay-per-call data agents on x402 (USDC on Base + Solana). This service scrapes the public Facebook Ad Library — every live and recent ad any advertiser runs across Facebook, Instagram, Messenger and Threads — and returns the full ad creative (headline, body copy, CTA + destination link, image and video URLs), the advertiser, run dates, and platform mix. Search by keyword/advertiser or monitor a specific page. Commercial and political ads, no Meta API or login, paid per call.","contact":{"email":"eldeebomar@gmail.com"},"version":"1.0.0","x-guidance":"Flat $0.03 per call. GET /v1/ads/facebook/search?q=<keyword> (or ?advertiser=<brand>) to discover who's advertising on a topic; GET /v1/ads/facebook/page?page=<facebook page url> to monitor one advertiser's ads. Filter by country (default US; ALL is a slower multi-region sweep), media_type, ad_type, platforms, period, active_status, sort_by, and limit (max 60). A call runs a live scrape and can take 20-90s. 4xx/5xx never charge (0 ads → 404). The page route locks to the dominant/resolved page and echoes resolvedPage. Note: spend + impressions ranges appear only when Meta's Ad Library discloses them (some political/issue ads) and are often absent — don't depend on them."},"servers":[{"url":"https://ads.apitoll.cloud"}],"tags":[{"name":"facebook-ads","description":"Facebook / Instagram ad data"},{"name":"ad-library","description":"Public ad library scraping"},{"name":"competitor-intelligence","description":"Competitor ad monitoring"},{"name":"ad-creative","description":"Ad creative + copy"},{"name":"apitoll","description":"ApiToll factory family"}],"paths":{"/v1/ads/facebook/search":{"get":{"operationId":"getAdsFacebookSearch","summary":"Search live + recent Facebook/Instagram ads by keyword across all advertisers","description":"Facebook Ad Library search by keyword — every live and recent ad matching a search term across all advertisers on Facebook, Instagram, Messenger and Threads. Returns the full ad creative (headline, body copy, CTA button + destination link, image and video URLs), the advertiser, run dates and days-running, and platform mix. Commercial and political ads, no Meta API or login. Competitor ad intelligence, ad spy, and creative research for AI agents.","tags":["facebook-ads","ad-library","ads","keyword-search"],"x-keywords":["facebook ad library","facebook ads scraper","scrape facebook ads","facebook ads","instagram ads","ad spy","search facebook ads","ad creative","meta ads","ad intelligence"],"x-use-cases":["Discover every brand advertising on a keyword/topic","Pull ad copy, CTAs and landing URLs for creative research","Track which ads run for a product category"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","default":"shoes"},"description":"Keyword/phrase to search ads for (e.g. \"running shoes\", \"crypto wallet\"). Defaults to a demo query if omitted."},{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"US"},"description":"Two-letter ISO country (US, GB, DE, BR…) the ads target, or ALL for a bounded multi-region sweep (slower). Default US."},{"name":"media_type","in":"query","required":false,"schema":{"type":"string","enum":["all","image","video","meme","image_and_meme","none"],"default":"all"},"description":"Creative format filter."},{"name":"ad_type","in":"query","required":false,"schema":{"type":"string","enum":["all","political_and_issue_ads","housing_ads","employment_ads","credit_ads","financial_products_and_services_ads"],"default":"all"},"description":"Ad category filter. political_and_issue_ads MAY add spend + impressions ranges when Meta discloses them (often absent)."},{"name":"platforms","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated publisher filter: FACEBOOK,INSTAGRAM,MESSENGER,AUDIENCE_NETWORK,THREADS,WHATSAPP. Blank = all."},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["","last24h","last7d","last14d","last30d"]},"description":"Limit to ads active in this window. Blank = all time."},{"name":"active_status","in":"query","required":false,"schema":{"type":"string","enum":["all","active","inactive"],"default":"all"},"description":"Filter by whether the ad is still running."},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","enum":["impressions_desc","most_recent"],"default":"most_recent"},"description":"most_recent (newest/currently-running first — default) or impressions_desc (all-time highest-impression ads, often older/ended)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":60,"default":25},"description":"Max ads to return (1-60)."},{"name":"resolve_advertiser","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Also resolve each advertiser’s page identity (verified status, categories, profile pic). Slower. Default false."}],"security":[{"x402":[]}],"x-payment-info":{"protocols":[{"x402":{"version":2,"network":"eip155:8453","asset":"USDC","assetAddress":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x4ce88238F669d04351937420C931988e464a975a","scheme":"exact","price":"$0.03"}},{"x402":{"version":2,"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","asset":"USDC","assetAddress":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","payTo":"HZ5rN5HmZpu2H16auY5Zt5SuJjCMBG77odVhAVSuhK1x","scheme":"exact","price":"$0.03"}}],"price":{"mode":"fixed","currency":"USD","amount":"0.03"}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"asOf":{"type":"string"},"query":{"type":"object","properties":{"keyword":{"type":"string"}}},"country":{"type":"string"},"count":{"type":"number"},"ads":{"type":"array","items":{"type":"object","properties":{"adArchiveId":{"type":"string"},"pageId":{"type":"string"},"pageName":{"type":"string"},"pageVerified":{"type":"boolean"},"isActive":{"type":"boolean"},"startDate":{"type":"number"},"daysRunning":{"type":"number"},"publisherPlatform":{"type":"array","items":{"type":"string"}},"displayFormat":{"type":"string"},"templatedText":{"type":"boolean"},"title":{"type":"string"},"bodyText":{"type":"string"},"ctaText":{"type":"string"},"ctaType":{"type":"string"},"linkUrl":{"type":"string"},"linkUrlType":{"type":"string"},"imageUrls":{"type":"array","items":{"type":"string"}},"videoUrl":{"type":"string"},"mediaExpiresAt":{"type":"string"},"country":{"type":"string"},"sourceUrl":{"type":"string"},"scrapedAt":{"type":"string"}}}},"source":{"type":"object","properties":{"name":{"type":"string"},"via":{"type":"string"}}}}}}}},"402":{"description":"Payment Required. Sign an x402 payment authorization and retry.","headers":{"Payment-Required":{"schema":{"type":"string"},"description":"Base64-encoded x402 v2 challenge."}},"content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No ads found for this query (unknown brand / blocked / empty) — not charged."},"405":{"description":"Method not allowed — use GET."},"502":{"description":"Facebook Ad Library (Apify) upstream unavailable or timed out — not charged."}}}},"/v1/ads/facebook/advertiser":{"get":{"operationId":"getAdsFacebookAdvertiser","summary":"A specific brand’s live + recent Facebook/Instagram ads by advertiser name","description":"Facebook ads from a specific advertiser by brand name — every live and recent ad a brand runs across Facebook, Instagram, Messenger and Threads, isolated to that ONE advertiser (filters out the stray pages a name search pulls in; echoes resolvedPage to verify). Returns the full ad creative (headline, body copy, CTA + destination link, image and video URLs), run dates, and platform mix. No Meta login. Competitor ad intelligence for AI agents.","tags":["facebook-ads","ad-library","competitor-intelligence","brand-ads"],"x-keywords":["facebook ad library","competitor ads","brand ads","advertiser ads","facebook ads scraper","ad spy","monitor competitor ads","meta ads","who is advertising"],"x-use-cases":["Monitor a competitor brand’s live ads","Pull all of a brand’s ad creative + offers","Track a specific advertiser over time"],"parameters":[{"name":"advertiser","in":"query","required":true,"schema":{"type":"string","default":"Nike"},"description":"Brand / advertiser NAME (e.g. Nike, Spotify, Samsung). Resolves to the dominant matching Facebook page. Defaults to a demo brand if omitted."},{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"US"},"description":"Two-letter ISO country (US, GB, DE, BR…) the ads target, or ALL for a bounded multi-region sweep (slower). Default US."},{"name":"media_type","in":"query","required":false,"schema":{"type":"string","enum":["all","image","video","meme","image_and_meme","none"],"default":"all"},"description":"Creative format filter."},{"name":"ad_type","in":"query","required":false,"schema":{"type":"string","enum":["all","political_and_issue_ads","housing_ads","employment_ads","credit_ads","financial_products_and_services_ads"],"default":"all"},"description":"Ad category filter. political_and_issue_ads MAY add spend + impressions ranges when Meta discloses them (often absent)."},{"name":"platforms","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated publisher filter: FACEBOOK,INSTAGRAM,MESSENGER,AUDIENCE_NETWORK,THREADS,WHATSAPP. Blank = all."},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["","last24h","last7d","last14d","last30d"]},"description":"Limit to ads active in this window. Blank = all time."},{"name":"active_status","in":"query","required":false,"schema":{"type":"string","enum":["all","active","inactive"],"default":"all"},"description":"Filter by whether the ad is still running."},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","enum":["impressions_desc","most_recent"],"default":"most_recent"},"description":"most_recent (newest/currently-running first — default) or impressions_desc (all-time highest-impression ads, often older/ended)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":60,"default":25},"description":"Max ads to return (1-60)."},{"name":"resolve_advertiser","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Also resolve the advertiser’s page identity (verified status, categories, profile pic). Slower. Default false."}],"security":[{"x402":[]}],"x-payment-info":{"protocols":[{"x402":{"version":2,"network":"eip155:8453","asset":"USDC","assetAddress":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x4ce88238F669d04351937420C931988e464a975a","scheme":"exact","price":"$0.03"}},{"x402":{"version":2,"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","asset":"USDC","assetAddress":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","payTo":"HZ5rN5HmZpu2H16auY5Zt5SuJjCMBG77odVhAVSuhK1x","scheme":"exact","price":"$0.03"}}],"price":{"mode":"fixed","currency":"USD","amount":"0.03"}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"asOf":{"type":"string"},"query":{"type":"object","properties":{"advertiser":{"type":"string"}}},"resolvedPage":{"type":"object","properties":{"pageId":{"type":"string"},"pageName":{"type":"string"}}},"country":{"type":"string"},"count":{"type":"number"},"ads":{"type":"array","items":{"type":"object","properties":{"adArchiveId":{"type":"string"},"pageId":{"type":"string"},"pageName":{"type":"string"},"isActive":{"type":"boolean"},"startDate":{"type":"number"},"daysRunning":{"type":"number"},"publisherPlatform":{"type":"array","items":{"type":"string"}},"displayFormat":{"type":"string"},"templatedText":{"type":"boolean"},"title":{"type":"string"},"bodyText":{"type":"string"},"ctaText":{"type":"string"},"ctaType":{"type":"string"},"linkUrl":{"type":"string"},"linkUrlType":{"type":"string"},"imageUrls":{"type":"array","items":{"type":"string"}},"mediaExpiresAt":{"type":"string"},"country":{"type":"string"},"sourceUrl":{"type":"string"},"scrapedAt":{"type":"string"}}}},"source":{"type":"object","properties":{"name":{"type":"string"},"via":{"type":"string"}}}}}}}},"402":{"description":"Payment Required. Sign an x402 payment authorization and retry.","headers":{"Payment-Required":{"schema":{"type":"string"},"description":"Base64-encoded x402 v2 challenge."}},"content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No ads found for this query (unknown brand / blocked / empty) — not charged."},"405":{"description":"Method not allowed — use GET."},"502":{"description":"Facebook Ad Library (Apify) upstream unavailable or timed out — not charged."}}}},"/v1/ads/facebook/page":{"get":{"operationId":"getAdsFacebookPage","summary":"All live + recent ads from a specific advertiser’s Facebook page","description":"Facebook ads from a specific advertiser page — monitor every live and recent ad a competitor runs by passing their Facebook page URL, vanity handle, or page id. Returns the full ad creative (headline, body copy, CTA + destination link, image and video URLs), run dates, and platform mix across Facebook, Instagram, Messenger and Threads. Track a competitor’s ad strategy and winning creatives over time. No Meta login.","tags":["facebook-ads","ad-library","competitor-monitoring","ad-creative"],"x-keywords":["facebook ad library","facebook ads scraper","competitor ads","ad monitoring","brand ads","ad spy","page ads","ad creative","track competitor advertising"],"x-use-cases":["Monitor a known competitor’s live ads over time","Audit which creatives + offers a brand is running","Track a page’s ad cadence and landing pages"],"parameters":[{"name":"page","in":"query","required":true,"schema":{"type":"string","default":"https://www.facebook.com/nike"},"description":"Facebook page URL (facebook.com/nike), vanity handle, profile.php?id=, or numeric page id. Defaults to a demo page if omitted."},{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"US"},"description":"Two-letter ISO country (US, GB, DE…) the ads target, or ALL for a bounded multi-region sweep (slower). Default US."},{"name":"media_type","in":"query","required":false,"schema":{"type":"string","enum":["all","image","video","meme","image_and_meme","none"],"default":"all"},"description":"Creative format filter."},{"name":"ad_type","in":"query","required":false,"schema":{"type":"string","enum":["all","political_and_issue_ads","housing_ads","employment_ads","credit_ads","financial_products_and_services_ads"],"default":"all"},"description":"Ad category filter. political_and_issue_ads MAY add spend + impressions ranges when Meta discloses them (often absent)."},{"name":"platforms","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated publisher filter: FACEBOOK,INSTAGRAM,MESSENGER,AUDIENCE_NETWORK,THREADS,WHATSAPP. Blank = all."},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["","last24h","last7d","last14d","last30d"]},"description":"Limit to ads active in this window. Blank = all time."},{"name":"active_status","in":"query","required":false,"schema":{"type":"string","enum":["all","active","inactive"],"default":"all"},"description":"Filter by whether the ad is still running."},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","enum":["impressions_desc","most_recent"],"default":"most_recent"},"description":"most_recent (newest/currently-running first — default) or impressions_desc (all-time highest-impression ads, often older/ended)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":60,"default":25},"description":"Max ads to return (1-60)."},{"name":"resolve_advertiser","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Also resolve the page identity (verified status, categories, profile pic). Slower. Default false."}],"security":[{"x402":[]}],"x-payment-info":{"protocols":[{"x402":{"version":2,"network":"eip155:8453","asset":"USDC","assetAddress":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x4ce88238F669d04351937420C931988e464a975a","scheme":"exact","price":"$0.03"}},{"x402":{"version":2,"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","asset":"USDC","assetAddress":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","payTo":"HZ5rN5HmZpu2H16auY5Zt5SuJjCMBG77odVhAVSuhK1x","scheme":"exact","price":"$0.03"}}],"price":{"mode":"fixed","currency":"USD","amount":"0.03"}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"asOf":{"type":"string"},"page":{"type":"string"},"resolvedPage":{"type":"object","properties":{"pageId":{"type":"string"},"pageName":{"type":"string"}}},"country":{"type":"string"},"count":{"type":"number"},"ads":{"type":"array","items":{"type":"object","properties":{"adArchiveId":{"type":"string"},"pageId":{"type":"string"},"pageName":{"type":"string"},"pageVerified":{"type":"boolean"},"isActive":{"type":"boolean"},"startDate":{"type":"number"},"daysRunning":{"type":"number"},"publisherPlatform":{"type":"array","items":{"type":"string"}},"displayFormat":{"type":"string"},"templatedText":{"type":"boolean"},"title":{"type":"string"},"bodyText":{"type":"string"},"ctaText":{"type":"string"},"ctaType":{"type":"string"},"linkUrl":{"type":"string"},"linkUrlType":{"type":"string"},"imageUrls":{"type":"array","items":{"type":"string"}},"mediaExpiresAt":{"type":"string"},"country":{"type":"string"},"sourceUrl":{"type":"string"},"scrapedAt":{"type":"string"}}}},"source":{"type":"object","properties":{"name":{"type":"string"},"via":{"type":"string"}}}}}}}},"402":{"description":"Payment Required. Sign an x402 payment authorization and retry.","headers":{"Payment-Required":{"schema":{"type":"string"},"description":"Base64-encoded x402 v2 challenge."}},"content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No ads found for this query (unknown brand / blocked / empty) — not charged."},"405":{"description":"Method not allowed — use GET."},"502":{"description":"Facebook Ad Library (Apify) upstream unavailable or timed out — not charged."}}}},"/v1/ads/tiktok/top":{"get":{"operationId":"getAdsTiktokTop","summary":"TikTok’s best-performing ads in a country by CTR/likes (global, incl. US + MENA)","description":"TikTok ad library — TikTok Creative Center’s global Top Ads leaderboard: the best-performing TikTok ads in any of 81 countries (incl. US and full MENA), ranked by TikTok’s CTR / likes / 2-second-view boards. Returns each ad’s video + cover image, advertiser brand (when disclosed), engagement (likes/comments/shares), landing page, a relative performance + cost index, and campaign objective. Creative trend research, winning-ad discovery, and TikTok ad spy for AI agents.","tags":["tiktok-ads","ad-library","tiktok-ad-library","creative-center"],"x-keywords":["tiktok ad library","tiktok ads scraper","scrape tiktok ads","tiktok ads","tiktok top ads","tiktok creative center","winning ads","ad spy","tiktok ad intelligence"],"x-use-cases":["Find the top-performing TikTok ads in a market","Pull winning ad videos + landing pages for creative research","Track TikTok ad trends by country / industry"],"parameters":[{"name":"country","in":"query","required":true,"schema":{"type":"string","default":"US"},"description":"Two-letter ISO country for the Top Ads leaderboard (US, GB, SA, AE, EG, DE, BR…; 81 supported incl. full MENA). Default US."},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["7","30","180"],"default":"30"},"description":"Look-back window in days."},{"name":"order_by","in":"query","required":false,"schema":{"type":"string","enum":["ctr","like","play_2s_rate","for_you","impression"],"default":"ctr"},"description":"Which TikTok leaderboard to pull (results are returned best-first by this metric)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":40,"default":20},"description":"Max ads to return (1-40)."},{"name":"detail","in":"query","required":false,"schema":{"type":"boolean","default":true},"description":"Enrich each ad with landing page URL + share/comment counts. Default true."}],"security":[{"x402":[]}],"x-payment-info":{"protocols":[{"x402":{"version":2,"network":"eip155:8453","asset":"USDC","assetAddress":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x4ce88238F669d04351937420C931988e464a975a","scheme":"exact","price":"$0.03"}},{"x402":{"version":2,"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","asset":"USDC","assetAddress":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","payTo":"HZ5rN5HmZpu2H16auY5Zt5SuJjCMBG77odVhAVSuhK1x","scheme":"exact","price":"$0.03"}}],"price":{"mode":"fixed","currency":"USD","amount":"0.03"}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"asOf":{"type":"string"},"country":{"type":"string"},"period":{"type":"string"},"orderBy":{"type":"string"},"count":{"type":"number"},"ads":{"type":"array","items":{"type":"object","properties":{"adId":{"type":"string"},"title":{"type":"string"},"brandName":{"type":"string"},"ctrIndex":{"type":"number"},"likes":{"type":"number"},"comments":{"type":"number"},"shares":{"type":"number"},"costIndex":{"type":"number"},"industryCode":{"type":"string"},"objective":{"type":"string"},"videoUrl":{"type":"string"},"coverImage":{"type":"string"},"coverExpiresAt":{"type":"string"},"landingPage":{"type":"string"},"country":{"type":"string"},"periodDays":{"type":"number"},"orderBy":{"type":"string"},"scrapedAt":{"type":"string"}}}},"source":{"type":"object","properties":{"name":{"type":"string"},"via":{"type":"string"}}}}}}}},"402":{"description":"Payment Required. Sign an x402 payment authorization and retry.","headers":{"Payment-Required":{"schema":{"type":"string"},"description":"Base64-encoded x402 v2 challenge."}},"content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No ads found for this query (unknown brand / blocked / empty) — not charged."},"405":{"description":"Method not allowed — use GET."},"502":{"description":"Facebook Ad Library (Apify) upstream unavailable or timed out — not charged."}}}}},"components":{"securitySchemes":{"x402":{"type":"apiKey","in":"header","name":"X-PAYMENT","description":"x402 v2 payment header. Flat $0.03 per response. USDC on eip155:8453 + solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp."}}}}