Ad library tools
Public ads by keyword, brand, and advertiser. Google uses DataForSEO; Meta, TikTok and LinkedIn are implemented through ScrapeCreators, with live account verification pending.
4 tools are implemented in this family. The definitions below come from the service’s actual tool catalog.
This family includes implemented tools with provider or platform limitations. Live provider verification is pending; read each description before using it.
Authenticate, inspect the schema, then request an estimate using dry_run where supported. Research can spend workspace credits.
Search an ad library
ads_search_adsAds in a platform's public library by keyword, product or brand (facebook, tiktok, linkedin). Google is not searchable by keyword: use ads_search_advertisers, then ads_get_advertiser_ads. Google uses DataForSEO. Meta, TikTok and LinkedIn use ScrapeCreators; live account verification is pending. TikTok country filters cover supported delivery countries and exclude US. active_only is Meta only. Returns rows[], one ad each: advertiser, headline, body, format, first_shown, last_shown, active, versions, impressions, spend, countries, placements, targeting[], cta, destination_url, media_url. Cost: Social libraries: 1 product credit per page. Cached 24 hours.
REST endpoint
POST /api/ads/tools/ads_search_adsProduct-credit cost
Social libraries: 1 product credit per page. Cached 24 hours.
Input JSON schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"platform": {
"type": "string",
"enum": [
"facebook",
"tiktok",
"linkedin"
],
"description": "Required. Google has no keyword search: use ads_search_advertisers first."
},
"query": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Required. Keyword, product or brand."
},
"country": {
"description": "Two-letter country code. Default: all countries supported by the library. TikTok excludes US.",
"type": "string",
"pattern": "^[A-Za-z]{2}$"
},
"active_only": {
"default": false,
"description": "Facebook only.",
"type": "boolean"
},
"cursor": {
"description": "The next page: meta.cursor from the previous result.",
"type": "string"
},
"max_credits": {
"description": "Refuse the call with BudgetExceeded if the estimate is higher.",
"type": "number",
"minimum": 0
},
"dry_run": {
"default": false,
"description": "Return only meta with the estimate. Costs nothing.",
"type": "boolean"
},
"idempotency_key": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{8,100}$"
}
},
"required": [
"platform",
"query"
]
}Find advertisers in Google or Meta's ad library
ads_search_advertisersAdvertisers matching a brand name in Google's Ads Transparency Center or Meta page search, with the ids ads_get_advertiser_ads takes. Returns rows[]: platform, id, name, region, ads_estimate, website. Cost: Google: 1 product credit. Meta: 1 product credit. Cached 7 days.
REST endpoint
POST /api/ads/tools/ads_search_advertisersProduct-credit cost
Google: 1 product credit. Meta: 1 product credit. Cached 7 days.
Input JSON schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"platform": {
"type": "string",
"enum": [
"google",
"facebook"
],
"description": "Required. Google advertiser search or Meta page search."
},
"query": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Required. Brand or company name."
},
"region": {
"description": "Google only. Two-letter code. A brand has one entry per region.",
"type": "string",
"pattern": "^[A-Za-z]{2}$"
},
"max_credits": {
"description": "Refuse the call with BudgetExceeded if the estimate is higher.",
"type": "number",
"minimum": 0
},
"dry_run": {
"default": false,
"description": "Return only meta with the estimate. Costs nothing.",
"type": "boolean"
},
"idempotency_key": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{8,100}$"
}
},
"required": [
"platform",
"query"
]
}Get an advertiser's ads
ads_get_advertiser_adsEvery ad one advertiser runs in a platform's public library. Google uses DataForSEO. Meta, TikTok and LinkedIn use ScrapeCreators; live account verification is pending. TikTok country filters cover supported delivery countries and exclude US. active_only is Meta only. Returns rows[]: advertiser, headline, body, format, first_shown, last_shown, active, versions, impressions, spend, countries, placements, targeting[], cta, destination_url, media_url. Impressions and spend are the ranges the library publishes, as text. Cost: Google: 1 product credit per page. Social libraries: 1 product credit per page. Cached 24 hours. Google details is unavailable.
REST endpoint
POST /api/ads/tools/ads_get_advertiser_adsProduct-credit cost
Google: 1 product credit per page. Social libraries: 1 product credit per page. Cached 24 hours. Google details is unavailable.
Input JSON schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"platform": {
"type": "string",
"enum": [
"facebook",
"tiktok",
"linkedin",
"google"
],
"description": "Required."
},
"advertiser": {
"type": "string",
"minLength": 1,
"maxLength": 300,
"description": "Required. google: a domain or advertiser id (AR...). facebook: page id or name. tiktok: advertiser name. linkedin: company name or id."
},
"country": {
"description": "Two-letter country code. Default: all countries supported by the library. TikTok excludes US.",
"type": "string",
"pattern": "^[A-Za-z]{2}$"
},
"active_only": {
"default": false,
"description": "Facebook only.",
"type": "boolean"
},
"details": {
"default": false,
"description": "Reserved Google option; details: true is currently unavailable.",
"type": "boolean"
},
"cursor": {
"description": "The next page: meta.cursor from the previous result.",
"type": "string"
},
"max_credits": {
"description": "Refuse the call with BudgetExceeded if the estimate is higher.",
"type": "number",
"minimum": 0
},
"dry_run": {
"default": false,
"description": "Return only meta with the estimate. Costs nothing.",
"type": "boolean"
},
"idempotency_key": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{8,100}$"
}
},
"required": [
"platform",
"advertiser"
]
}Get one ad
ads_get_adOne ad with its creative text and destination, and where published, audience and reach. Google uses DataForSEO. Meta, TikTok and LinkedIn use ScrapeCreators; live account verification is pending. TikTok country filters cover supported delivery countries and exclude US. active_only is Meta only. Returns advertiser, headline, body, format, first_shown, last_shown, active, versions, impressions, spend, countries, placements, targeting[], cta, destination_url, media_url, variations[] (text variants on google), reach, reach_by_country[], reach_by_age_gender[], payers[] (Meta EU and UK disclosures only; null on google). Cost: Google: 1 product credit. Social libraries: 1 product credit. Cached 7 days.
REST endpoint
POST /api/ads/tools/ads_get_adProduct-credit cost
Google: 1 product credit. Social libraries: 1 product credit. Cached 7 days.
Input JSON schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"platform": {
"type": "string",
"enum": [
"facebook",
"tiktok",
"linkedin",
"google"
],
"description": "Required."
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"description": "Required. Ad id on facebook and tiktok; ad URL on linkedin and google."
},
"max_credits": {
"description": "Refuse the call with BudgetExceeded if the estimate is higher.",
"type": "number",
"minimum": 0
},
"dry_run": {
"default": false,
"description": "Return only meta with the estimate. Costs nothing.",
"type": "boolean"
},
"idempotency_key": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{8,100}$"
}
},
"required": [
"platform",
"id"
]
}