{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Ads Transparency Scraper — Fast, Reliable, Watch Mode",
    "description": "Get an advertiser's Google ads by domain, advertiser ID, or Transparency Center URL. Returns creative images, OCR'd headline/body text, format, and shown dates. Watch mode returns only new ads.",
    "version": "0.2",
    "x-build-id": "61LAIAND3dMSMjQMz"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/domestic_buffalograss~google-ads-transparency-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-domestic_buffalograss-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/domestic_buffalograss~google-ads-transparency-scraper/runs": {
      "post": {
        "operationId": "runs-sync-domestic_buffalograss-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/domestic_buffalograss~google-ads-transparency-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-domestic_buffalograss-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": {
          "queries": {
            "title": "Advertiser domains to search",
            "type": "array",
            "description": "Search the Ads Transparency Center by advertiser domain, e.g. <code>nike.com</code>. One search per entry. Use the registrable domain — a bare brand name (<code>nike</code>) or a full URL usually matches no advertiser.",
            "items": {
              "type": "string"
            }
          },
          "advertiserIds": {
            "title": "Advertiser IDs (AR...)",
            "type": "array",
            "description": "Scrape all ads of specific advertisers by their <code>AR…</code> IDs (find them in any Transparency Center URL).",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Transparency Center URLs",
            "type": "array",
            "description": "Paste advertiser page URLs from adstransparency.google.com — advertiser IDs are extracted automatically.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "maxItems": {
            "title": "Max ads (cost cap)",
            "minimum": 1,
            "maximum": 1000000,
            "type": "integer",
            "description": "Hard stop after this many ads, across all searches. You are charged per ad returned, so this caps that charge — the run start, and the optional creative details and archived images, are billed separately. Use the run's <b>Max total charge</b> setting for a single hard limit. This budget is shared by all searches in the run: put many brands in one run only if the cap can cover them all.",
            "default": 500
          },
          "region": {
            "title": "Region (country)",
            "pattern": "^([A-Za-z]{2}|anywhere|ANYWHERE|all|ALL)$",
            "type": "string",
            "description": "Two-letter country code - <code>US</code>, <code>JP</code>, <code>GB</code>, <code>DE</code> - or <code>anywhere</code> for all regions. This is where the ad was shown, not where the advertiser is based.",
            "default": "anywhere"
          },
          "creativeFormat": {
            "title": "Creative format",
            "enum": [
              "ALL",
              "TEXT",
              "IMAGE",
              "VIDEO"
            ],
            "type": "string",
            "description": "Filter by ad format.",
            "default": "ALL"
          },
          "platforms": {
            "title": "Platforms",
            "type": "array",
            "description": "Only ads shown on these Google surfaces. Leave empty for all. Note that Google only supports this filter for ads shown since 4 September 2023.",
            "items": {
              "type": "string",
              "enum": [
                "SEARCH",
                "YOUTUBE",
                "MAPS",
                "SHOPPING",
                "PLAY"
              ],
              "enumTitles": [
                "Google Search",
                "YouTube",
                "Google Maps",
                "Google Shopping",
                "Google Play"
              ]
            }
          },
          "firstShownAfter": {
            "title": "First shown after",
            "type": "string",
            "description": "ISO date (e.g. <code>2026-07-01</code>) — keep only ads first shown on/after this date."
          },
          "lastShownAfter": {
            "title": "Last shown after",
            "type": "string",
            "description": "ISO date — keep only ads still shown on/after this date (active-recently filter)."
          },
          "onlyNewCreatives": {
            "title": "Watch mode - output only newly launched ads",
            "type": "boolean",
            "description": "Remembers every creative seen in previous runs (per <b>State key</b>) and outputs only the ones that have appeared since. Ads that are simply still running are not repeated — see the option below if you want those too. The memory has to cover the advertiser before \"new\" means \"just launched\", so let the first run finish without hitting <b>Max ads</b>; the run warns you if it could not.",
            "default": false
          },
          "stateKey": {
            "title": "State key (watch mode)",
            "type": "string",
            "description": "Separate watch memories for different projects, e.g. <code>client-a</code>. Give concurrent schedules different state keys — two runs sharing one key at the same time will overwrite each other's memory.",
            "default": "default"
          },
          "includeUpdated": {
            "title": "Also output ads that are still running",
            "type": "boolean",
            "description": "Off by default. Google refreshes the last-shown date of every live ad continuously, so turning this on makes each watch run return the advertiser's whole active inventory instead of just their launches — useful for tracking activity levels, expensive as an alert feed.",
            "default": false
          },
          "overlapHours": {
            "title": "Watch overlap window (hours)",
            "minimum": 0,
            "maximum": 720,
            "type": "integer",
            "description": "Watch mode stops scanning once it reaches ads older than the previous run, minus this safety margin. Larger = safer against late updates on Google's side, slower and slightly more expensive.",
            "default": 24
          },
          "fullScanEveryNRuns": {
            "title": "Full rescan every N runs",
            "minimum": 0,
            "type": "integer",
            "description": "Watch mode periodically re-reads the advertiser's whole inventory to catch anything the incremental scan could have missed and to forget ads Google has removed. <code>0</code> disables it.",
            "default": 7
          },
          "fetchCreativeDetails": {
            "title": "Fetch creative details",
            "type": "boolean",
            "description": "One extra request per ad: all render variants of the creative. Charged as a separate event.",
            "default": false
          },
          "extractAdText": {
            "title": "Read the ad text out of the creative",
            "type": "boolean",
            "description": "Google archives text ads as <b>images</b>, so a search ad's headline and body exist nowhere in its data - only in the picture. Turn this on to run OCR over the creative and return what it says in <code>creativeText</code>. Charged per ad only when readable text actually comes out: video ads and wordless banners are free. This is OCR output, not a field Google publishes, so expect occasional misreads - <code>creativeTextSource</code> records where it came from. <b>For image and shopping ads, turn on <i>Archive creative images</i> too</b>: those have no direct image URL until it is resolved, and without it there is nothing to read. <code>RUN_SUMMARY.adText</code> counts exactly why any ad came back without text.",
            "default": false
          },
          "downloadAssets": {
            "title": "Archive creative images",
            "type": "boolean",
            "description": "Keep copies of the ad images in this run's key-value store (Google's URLs expire). Charged per stored image, up to 10 per ad. Also resolves the image URLs and <code>youtubeVideoId</code> for image, shopping and video ads, which Google serves through a renderer rather than a direct link.",
            "default": false
          },
          "resolveAdvertiserInfo": {
            "title": "Resolve advertiser info",
            "type": "boolean",
            "description": "Add the advertiser's verified legal name and country (one cached request per advertiser).",
            "default": true
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Proxies to use. Residential proxies are required in practice: Google's Ads Transparency Center rate-limits (HTTP 429) datacenter IPs on every request, so a run on the automatic/datacenter pool returns nothing. Measured 2026-08-22: same search, residential 10/10 ads in 10s, datacenter 0 ads and 6/6 requests rate-limited.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          }
        }
      },
      "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}