Ad library tools

Public ads by keyword, brand, and advertiser. Google's library is available; Meta, TikTok and LinkedIn need a social data provider.

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_ads

Ads 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. On this server only platform google is available; facebook, tiktok and linkedin are refused at no charge until a social data provider is connected. 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: 1 credit per page. Cached 24 hours.

REST endpoint

POST /api/ads/tools/ads_search_ads

Product-credit cost

1 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: every country in the library.",
      "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's ad library

ads_search_advertisers

Advertisers matching a brand name in Google's Ads Transparency Center, with the ids ads_get_advertiser_ads takes. Returns rows[]: platform, id, name, region, ads_estimate, website. Cost: 1 credit. Cached 7 days.

REST endpoint

POST /api/ads/tools/ads_search_advertisers

Product-credit cost

1 credit. Cached 7 days.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "platform": {
      "type": "string",
      "enum": [
        "google"
      ],
      "description": "Required. Only Google keys its library by advertiser."
    },
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Required. Brand or company name."
    },
    "region": {
      "description": "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_ads

Every ad one advertiser runs in a platform's public library. On this server only platform google is available; facebook, tiktok and linkedin are refused at no charge until a social data provider is connected. 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: 1 credit per page; on google with details, 25 credits. Cached 24 hours.

REST endpoint

POST /api/ads/tools/ads_get_advertiser_ads

Product-credit cost

1 credit per page; on google with details, 25 credits. 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",
        "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: every country in the library.",
      "type": "string",
      "pattern": "^[A-Za-z]{2}$"
    },
    "active_only": {
      "default": false,
      "description": "Facebook only.",
      "type": "boolean"
    },
    "details": {
      "default": false,
      "description": "Google only: also fetch each creative's text. 25 credits.",
      "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_ad

One ad with its creative text and destination, and where published, audience and reach. On this server only platform google is available; facebook, tiktok and linkedin are refused at no charge until a social data provider is connected. 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: 1 credit. Cached 7 days.

REST endpoint

POST /api/ads/tools/ads_get_ad

Product-credit cost

1 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"
  ]
}