# Ad library tools

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

## Search an ad library

Tool: `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.

Endpoint: `POST /api/ads/tools/ads_search_ads`

Cost: 1 credit per page. Cached 24 hours.

### Input JSON schema

```json
{
  "$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

Tool: `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.

Endpoint: `POST /api/ads/tools/ads_search_advertisers`

Cost: 1 credit. Cached 7 days.

### Input JSON schema

```json
{
  "$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

Tool: `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.

Endpoint: `POST /api/ads/tools/ads_get_advertiser_ads`

Cost: 1 credit per page; on google with details, 25 credits. Cached 24 hours.

### Input JSON schema

```json
{
  "$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

Tool: `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.

Endpoint: `POST /api/ads/tools/ads_get_ad`

Cost: 1 credit. Cached 7 days.

### Input JSON schema

```json
{
  "$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"
  ]
}
```