{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Ads Transparency Scraper API: Competitor Ads Library",
    "description": "Competitor ad tracker for Google Ads Transparency via API: ads by domain, name or ID with first/last shown dates, impression ranges (mainly EU), optional own-ads filter and new-ad alerts to Slack. Summary says which competitors were read in full. $0.60/1,000 ads on Free; ad text +$0.15/1,000.",
    "version": "0.1",
    "x-build-id": "QSp9c62UfJx7PKFhG"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/fetchwright~google-ads-transparency-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-fetchwright-google-ads-transparency-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/fetchwright~google-ads-transparency-scraper/runs": {
      "post": {
        "operationId": "runs-sync-fetchwright-google-ads-transparency-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/fetchwright~google-ads-transparency-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-fetchwright-google-ads-transparency-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "targets": {
            "title": "Advertisers to look up",
            "type": "array",
            "description": "Required, unless you read targets from a dataset (see Chain with other Actors). One per line: a website domain (nike.com), an advertiser name (Nike), an advertiser ID (AR16735076323512287233) or an Ads Transparency Center URL. A URL's own country, format and dates apply to it where you leave those fields unset. Domains give the most complete results. With **Microsoft Advertising** chosen below: the advertiser's name as Microsoft lists it (Booking.com B.V.) or its numeric Microsoft advertiser ID (4295086664); Microsoft cannot be searched by website, so a domain is reported as not usable for that target.",
            "items": {
              "type": "string"
            }
          },
          "adNetwork": {
            "title": "Ad network",
            "enum": [
              "google",
              "microsoft"
            ],
            "type": "string",
            "description": "Which ad library to read. **Google** (the default) reads the Google Ads Transparency Center. **Microsoft Advertising** reads Microsoft's ad library of Bing ads shown in the European Economic Area: ad text, landing page, images and, with **Include variations, countries, impressions and platforms** on, first and last shown dates, the impression range, the share per country, targeting types and who paid. Same price per ad.",
            "default": "google"
          },
          "maxAdsPerTarget": {
            "title": "Maximum ads per advertiser",
            "minimum": 1,
            "type": "integer",
            "description": "Stop after this many ads for each domain or advertiser, for example **100**. You pay per ad saved, so this caps the cost of a run. Default: 100.",
            "default": 100
          },
          "region": {
            "title": "Country where the ads were shown",
            "type": "string",
            "description": "Country name or two-letter code, such as **US**, **GB**, **Germany**, **Deutschland** or **SE** (names are read in English and in the country's own language, without regard to accents). Use **ANYWHERE** for all countries (the default). A value read this way is noted in the run summary (inputNotes); a value that cannot be read stops the run before any ad is read or charged, naming the value and the accepted forms. For several countries in one run, use **Countries** below. With **Microsoft Advertising**, use ANYWHERE (all EEA countries) or one country of the European Economic Area such as **DE** or **FR**; with any other country the run searches all EEA countries and says so in the run summary.",
            "default": "ANYWHERE"
          },
          "regions": {
            "title": "Countries (several in one run)",
            "type": "array",
            "description": "Optional. Several countries in one run, for example **US**, **United Kingdom**, **Deutschland**. Each advertiser's list is read once per country and each ad is saved and charged once, with `matchedRegions` naming the countries whose list showed it. The maximum ads per advertiser applies across all countries together, so a run costs no more than with one country. When set, it replaces **Country** above. Google ads only: political ads, advertiser summaries and Microsoft Advertising read the first country given.",
            "items": {
              "type": "string"
            }
          },
          "maxAdsPerRun": {
            "title": "Maximum ads per run",
            "minimum": 1,
            "type": "integer",
            "description": "Stop the whole run after this many ads in all, across every domain, name and advertiser, for example **1000**. Use it for long lists, where the maximum per advertiser alone multiplies with the number of targets. Targets not reached are listed as unfinished in the run summary and are not charged. Leave empty for no run-wide maximum."
          },
          "continueFromLastRun": {
            "title": "Continue from the last run",
            "type": "boolean",
            "description": "On: when a run stops before every target is finished (Google refused it, the timeout, the maximum charge or the maximum ads per run), its place is kept, and the next run with the same input (or the same **Monitor name**) reads only the targets left, continuing a target from the page it reached. Ads an earlier run saved are never saved or charged again. When every target is finished, the place is removed and the next run starts from the beginning. Turn it on for the first run too: a run with it off keeps no place. The place is kept in a key-value store named google-ads-transparency-continue in your account for 7 days (a few writes per run; Apify lists key-value store writes at $0.05 per 1,000 on Free and Starter). Google ads only. Off (default): every run reads its targets from the start.",
            "default": false
          },
          "resultType": {
            "title": "What to return",
            "enum": [
              "ads",
              "advertisers"
            ],
            "type": "string",
            "description": "**Ads** lists one row per ad, up to your maximum per advertiser. **Advertiser summary** returns one row per company saying whether it advertises on Google, roughly how many ads it has, which advertiser accounts run them and in which formats. Use the summary to qualify a list of leads cheaply: it is one row per domain.",
            "default": "ads"
          },
          "format": {
            "title": "Ad format",
            "enum": [
              "ALL",
              "TEXT",
              "IMAGE",
              "VIDEO"
            ],
            "type": "string",
            "description": "Limit results to one ad format, for example **Video** for YouTube and video ads or **Text** for Search ads. Default: all formats.",
            "default": "ALL"
          },
          "platforms": {
            "title": "Google platforms",
            "type": "array",
            "description": "Keep only ads that ran on these Google platforms, for example **YouTube** or **Google Search**. Leave empty for all platforms. Works for every country and costs nothing extra.",
            "items": {
              "type": "string",
              "enum": [
                "GOOGLE_SEARCH",
                "YOUTUBE",
                "GOOGLE_SHOPPING",
                "GOOGLE_MAPS",
                "GOOGLE_PLAY"
              ],
              "enumTitles": [
                "Google Search",
                "YouTube",
                "Google Shopping",
                "Google Maps",
                "Google Play"
              ]
            }
          },
          "dateFrom": {
            "title": "Shown on or after",
            "type": "string",
            "description": "Keep ads that were still running on or after this date, for example **2026-10-01**. Also accepted: 01.10.2026, 1 Oct 2026, and a time before today such as **30 days**, **2 weeks** or **3 months** (counted back from the day of the run). A value that cannot be read (for example 11/09/2026, where day and month are unclear) stops the run before any ad is read or charged. Leave empty for no lower bound."
          },
          "dateTo": {
            "title": "Shown on or before",
            "type": "string",
            "description": "Keep ads that started on or before this date, for example **2026-10-31**. Also accepted: 31.10.2026, 31 Oct 2026, **today**, or a time before today such as **7 days**. A value that cannot be read stops the run before any ad is read or charged. Leave empty for no upper bound."
          },
          "politicalAds": {
            "title": "Political ads only",
            "type": "boolean",
            "description": "Reads Google's political (election) ads instead of all ads, with the spend range Google states (in the region's currency), times shown and, with details on, the age, gender and location targeting the advertiser chose. Needs a country Google's political ads report covers: AR, AU, BR, CL, GB, IL, IN, MX, NZ, TW, US or ZA. Same price per ad. Google's political ad data names funding organisations and can name natural persons; you are responsible for lawful use. Default: off.",
            "default": false
          },
          "onlyNewAds": {
            "title": "Only ads not returned in earlier runs",
            "type": "boolean",
            "description": "For scheduled monitoring, for example a daily run on your competitors. The Actor records which ads it returned for each advertiser, country and format. With one run of a watch at a time, it returns and charges only ads it has not recorded as returned. Two overlapping runs of the same watch, or a run killed before it saved its memory, can return an ad again. Default: off.",
            "default": false
          },
          "monitorName": {
            "title": "Monitor name",
            "type": "string",
            "description": "Optional. Give each scheduled watch its own name, for example **sportswear-us**, so several new-ads-only watches in one account keep separate memories. Leave empty to identify the watch by its target, country and format."
          },
          "firstRunBehaviour": {
            "title": "On a watch's first run",
            "enum": [
              "return_current",
              "remember_only"
            ],
            "type": "string",
            "description": "Applies with **Only ads not returned in earlier runs**. **Return current ads** returns the advertiser's current ads up to your cap on the first run. **Only remember** returns nothing on the first run, so the next run starts from new ads only. In both cases older ads are remembered without charge and are never returned as new later.",
            "default": "return_current"
          },
          "notifyWebhookUrl": {
            "title": "Send an alert to Slack, Discord or a webhook",
            "type": "string",
            "description": "Optional. Paste a Slack or Discord incoming-webhook address, or any https:// address that accepts JSON. When the run saves ads, a short message is posted there: how many ads per advertiser, the first three with their headline and link, and a link to all rows. With **Only new ads** on a schedule this is a competitor-ad alert. No extra charge."
          },
          "writeReport": {
            "title": "Write a client-ready report (free)",
            "type": "boolean",
            "description": "At the end of the run, turn the ads saved in this run into a report you can send to a client: REPORT.html and REPORT.md in the run storage, linked from the run summary. For example, run three competitor domains and forward the page to the client. Every figure is counted from this run's rows and every sentence comes from a fixed template; no AI model writes it. A report is written when the run has ads from two or more advertisers and at least one advertiser account has its whole list read or at least 100 ads saved. The ads of a domain are often spread over several advertiser accounts, so with domains set \"Maximum ads per advertiser\" to 200 or more (500 reads most whole lists). Free.",
            "default": false
          },
          "includeAdText": {
            "title": "Include ad text (+$0.15 per 1,000 ads with text)",
            "type": "boolean",
            "description": "Adds the ad's wording. For Search text ads it is Google's exact text where Google's preview carries it (`adTextStatus` `found`); otherwise the headline, description and display URL are read from the ad image (`read_from_image`, with a confidence score). In a test on monday.com in the US on 11 November 2026, wording was returned for 39 of 40 ads. For video and app ads it adds the YouTube video, description, call to action and destination URL where Google's preview carries them, and for Shopping ads the product, price and merchant. Each ad also lists the offers its wording states under `offers` (free trial, discount, promo code, price and more), and with **Only ads not returned in earlier runs** the run summary says which offers are newly observed since the previous run. Ad text +$0.15 per 1,000 ads with text, on every plan, charged once per saved ad with non-empty wording successfully read. No ad-text charge when the wording is unavailable or this switch is off (the default). One extra request per ad (about 1.3 seconds each); Search text ads read from the image take about 3 seconds each. Give the run 1 GB of memory or more to speed it up.",
            "default": false
          },
          "adTextLimit": {
            "title": "Ad text for the first ads only",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "With **Include ad text** on, read the wording for at most this many ads per advertiser, starting with the ads Google lists first, and save the rest without it. Search text ads take about 3 seconds each, so a limit keeps large runs fast: for example **25** gives a wording sample of each advertiser while the full list is still saved. Leave empty to read the wording of every ad."
          },
          "includeDetails": {
            "title": "Include variations, countries, impressions and platforms",
            "type": "boolean",
            "description": "Adds every variation of each ad, the countries where it was shown with first and last shown dates, the impression range Google publishes (mainly for ads shown in the EU) the Google platforms it ran on, and which audience criteria the advertiser used where Google publishes them. Makes one extra request per ad, so runs are slower. With **Microsoft Advertising**: first and last shown dates, the impression range, the share of impressions per country, the targeting types used and who paid, one extra request per ad. Microsoft runs with details are slower: allow about 20 seconds per Microsoft request before source response time and any slowdown; this is not a guaranteed quota.",
            "default": false
          },
          "includeAdvertiserIdentity": {
            "title": "Include advertiser country and verification",
            "type": "boolean",
            "description": "Adds the advertiser's registered country, its verification status (verified true, not verified false, unknown null) and, for verified advertisers, its legal name (`advertiserLegalName`) to ad rows and advertiser summary rows. Google: an advertiser found by its name gets these from that name search itself, with no extra lookup; for other targets (domains, IDs, links) they come from extra lookups unless already found in an earlier search (under a domain, for the domain's own advertiser accounts, or with none matched its most frequent account: other advertisers' rows keep null values unless already found), and are unknown beyond **Advertiser identity lookups per run** or when Google's advertiser search does not return the advertiser. Advertiser summary rows of a target given by name carry them from the name search whatever this setting, and with this off, Google ad rows of a target given by name still carry the country from the name search. Microsoft rows take the country and verification status from Microsoft (no legal name). The run summary counts rows with and without identity under `identity`. No extra charge.",
            "default": true
          },
          "identityLookupLimit": {
            "title": "Advertiser identity lookups per run",
            "minimum": 0,
            "maximum": 1000,
            "type": "integer",
            "description": "How many extra Google advertiser searches one run may make to find the country and verification status of advertisers not found by a name search (targets given as a domain, ID or link), unless already found in an earlier search. An advertiser found by its name needs no extra lookup and does not count. Advertisers beyond this number keep null values, and the run summary says so under `identity.stoppedBecause`. Microsoft rows are not affected. Under a domain, lookups go to the domain's own advertiser accounts (`isDomainAdvertiser` true; with none matched, to the account with the most ads listed), never to an account known to be another advertiser's, so other advertisers linked to the domain do not use them up; their count is under `identity.otherAdvertisersNotLookedUp`. To get identity for another advertiser, give its advertiser ID as a target. No extra charge; each lookup adds a second or two to the run.",
            "default": 25
          },
          "onlyDomainAdvertisers": {
            "title": "Domains: only the domain's own advertiser accounts",
            "type": "boolean",
            "description": "Google lists, under a domain, ads of the domain owner and ads of other advertisers it links to that domain (for hubspot.com in the US on 16 Nov 2026, 58 of 200 ads came from 42 other advertisers, mostly HubSpot customers). Every ad row of a domain target carries `isDomainAdvertiser`: true for the domain's own accounts, false for another advertiser, null when not known. On: only rows with true are saved and charged; the others are left out and not charged, and the run summary counts them. An account is the domain's own when its whole name, without legal endings, spells the domain's name (\"Hubspot, Inc.\" for hubspot.com, not \"HubSpot Partner Agency\") or its ads show the domain itself or www. of it as their address and it carries a real share of them (at least 3 ads in the domain's list, or 10% of the ads of the accounts matched to the domain); a one-off account linking to the domain is null with `linksToDomain` true, left out and not charged; an ad on another site marks another advertiser. Addresses come from ad text, so with ad text off only the name decides; wording read only to decide an ad that is then left out does not count toward the ad text limit. A brand whose account name differs from its domain and whose ads carry no readable address can be left out entirely; check `domainAdvertisers` per target in the run summary. Off (default): every row is saved and charged as before, with the field. Identity lookups go to the domain's own accounts (with none matched, to its most frequent account), either way. A watch remembers other advertisers' ads without returning or charging them. Advertiser IDs, names and links are not affected.",
            "default": false
          },
          "includeTargetsWithoutAds": {
            "title": "Advertiser summary: also save companies without ads",
            "type": "boolean",
            "description": "In advertiser summary mode, also saves a row for each company with no Google ads in the chosen country (`hasAds` false, `targetStatus` `no_ads_in_region` or `no_advertiser_found`), so the dataset lines up with your list; each such row is charged as one row. Off by default: a company without ads then gets no row and no charge, and is listed under `noAdsTargets` in the run summary. A company that could not be checked is never charged and never shown as having no ads: it is listed under `failedTargets` or `unfinishedTargets`.",
            "default": false
          },
          "notifyWhenNothingFound": {
            "title": "Alert even when nothing was saved",
            "type": "boolean",
            "description": "Also post a message when the run saved no ads. Off by default, so a quiet day sends nothing.",
            "default": false
          },
          "maxAdvertisersPerName": {
            "title": "Advertisers per name search",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "A name such as **Nike** can match several advertiser accounts. This sets how many to include, starting with the accounts that have the most ads. Default: 1.",
            "default": 1
          },
          "targetsDatasetId": {
            "title": "Read targets from a dataset",
            "type": "string",
            "description": "Optional. Pick a dataset from another run, for example a list of company domains or this Actor's own advertiser summary, and its values are added to the targets above. Use it to chain Actors without exporting anything."
          },
          "targetsDatasetField": {
            "title": "Dataset field",
            "type": "string",
            "description": "Name of the field that holds the domains, names or advertiser IDs, for example **domain** or **website**. Leave empty to detect it automatically (domain, website, url, searchTarget, advertiserId, advertiserName, name)."
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "For Google runs on Apify, the default is an Apify datacenter session. Omit this field to use it; set {\"useApifyProxy\": false} to go direct. Your explicit proxy settings are respected. Normal Google reads keep their existing pace, with no per-session request cap. At most two sessions are used in a run. If the first Google request on a datacenter session is blocked or rate-limited, the run waits 60–120 seconds and retries it once on a new session when the timeout allows, with no extra charge. Later refusals stop further Google reads. Locally, omitted settings stay direct. Microsoft uses only the proxy settings you explicitly select."
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}