{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Ads Transparency API & Scraper: Ad Library, Monitor, MCP",
    "description": "Google Ads Transparency scraper, Google Ads Library API, ad spy tool and competitor ad monitor: every ad a brand runs on Google Search, YouTube, Shopping and Maps, with ad copy and targeting. Google political ads with spend, ads Google removed, Slack, Discord or Teams alerts for new and stopped ads.",
    "version": "0.1",
    "x-build-id": "SBsmfedAeiWQjwiXf"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/akhil_rajesh~google-ads-transparency-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-akhil_rajesh-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/akhil_rajesh~google-ads-transparency-scraper/runs": {
      "post": {
        "operationId": "runs-sync-akhil_rajesh-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/akhil_rajesh~google-ads-transparency-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-akhil_rajesh-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": {
          "advertisers": {
            "title": "Advertisers or domains",
            "type": "array",
            "description": "What to read: a website's domain ('nike.com': every advertiser's ads that point to it), an advertiser's Transparency Center link (adstransparency.google.com/advertiser/AR...) or id (AR16735076323512287233), an ad's link (.../creative/CR..., read with its details), or an advertiser's name ('Nike': the accounts named so, biggest first). A pasted Transparency Center link keeps its own region, platform, format and dates (Last 7 days, a date range) when you set none here; a political page link (.../political?region=US) reads that region's political ads, a removed ads link (.../removed) the removed-ads feed. Names go through Google's search box, which sometimes refuses Apify's servers; domains, ids and links always work. Brands often advertise under their legal name, so a domain finds them all. Leave empty with Political ads on for every political ad of the region.",
            "items": {
              "type": "string"
            }
          },
          "region": {
            "title": "Region",
            "type": "string",
            "description": "The country the ads were shown in, by name or two-letter code ('United States', 'US', 'Germany', 'DE'), or 'anywhere' (the default: every region). A pasted Transparency Center link keeps its own region when this is empty. Political ads are listed by region ('EU' for the European Union; the United States when empty)."
          },
          "adFormat": {
            "title": "Ad format",
            "enum": [
              "all",
              "text",
              "image",
              "video"
            ],
            "type": "string",
            "description": "Only ads of this format, as the Transparency Center's own filter calls them (Search ads are text ads)."
          },
          "platform": {
            "title": "Platform",
            "enum": [
              "all",
              "search",
              "youtube",
              "shopping",
              "maps",
              "play"
            ],
            "type": "string",
            "description": "Only ads shown on this Google platform (the Transparency Center filters by one at a time)."
          },
          "shownWithinDays": {
            "title": "Shown within (days)",
            "minimum": 1,
            "maximum": 365,
            "type": "integer",
            "description": "Only ads Google showed in the last N days before today, as the Transparency Center's own 'Last 7 days' counts them: 2 for the ads running now, 30 for the last month. Its date filter reaches back about a year (365). Leave empty for every ad."
          },
          "startDate": {
            "title": "Shown from",
            "type": "string",
            "description": "Or a date window: only ads shown on or after this day (within the last year)."
          },
          "endDate": {
            "title": "Shown to",
            "type": "string",
            "description": "Only ads shown on or before this day (the day itself included)."
          },
          "maxResults": {
            "title": "Max results",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "Most ads a run returns, shared between the advertisers and domains. With Only changes: most changes a run returns (new ads first; the rest come with the next run).",
            "default": 1000
          },
          "maxAdsPerAdvertiser": {
            "title": "Max ads per advertiser",
            "minimum": 0,
            "maximum": 20000,
            "type": "integer",
            "description": "Most ads read per advertiser account or domain, newest shown first (Google lists up to tens of thousands for the biggest). 0 returns only each advertiser's row with Google's estimate of its ads: a quick check of which companies run Google ads.",
            "default": 1000
          },
          "accountsPerName": {
            "title": "Accounts per name",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "For an advertiser given by name: how many of the accounts named so to read, biggest first (accounts with under a tenth of the biggest one's ads are left out).",
            "default": 3
          },
          "maxAdDetails": {
            "title": "Ads to read in full (copy and details)",
            "minimum": 0,
            "maximum": 500,
            "type": "integer",
            "description": "Read this many ads in full per run (at most 500): a text ad's copy (headline, description, display URL, sitelinks, callouts, locations) where Google serves it as text (some advertisers' text ads, not all), a video's YouTube link, a Shopping or Maps ad's words, the Google Ads account and ad group behind the ad, and every ad's variations, regions (with Google's times-shown ranges, topic and audience selection for ads shown in the EU) and platforms. About a second or two per ad. With Only changes, the changes are read first. 0 for the fastest runs.",
            "default": 0
          },
          "politicalAds": {
            "title": "Political ads",
            "type": "boolean",
            "description": "Read political (election) ads: each with Google's range of how much was spent on it and how many times it was shown, and the political regions it belongs to; with ad details, its targeting (ages, genders, places included and excluded) and reach per region. Read for the advertisers and domains above, or, with none given, every political ad of the region (the United States if Region is empty). Google publishes spend for the US, the UK, the EU, India, Brazil, Australia, Israel, New Zealand, Taiwan, Mexico, Argentina, Chile and South Africa; political ads reach back to May 2018."
          },
          "candidateName": {
            "title": "Candidate name",
            "type": "string",
            "description": "Only political ads that name this candidate (the Transparency Center's own candidate search). Switches on Political ads."
          },
          "minSpend": {
            "title": "Min amount spent",
            "minimum": 0,
            "type": "integer",
            "description": "Only political ads with at least this much spent on them, in the region's currency (USD in the US, GBP in the UK, EUR in the EU, INR in India, and so on), rounded down to Google's spend brackets (in the US: 100, 1,000, 5,000, 10,000, 50,000, 100,000, 250,000, 500,000, 1M, 3M). Switches on Political ads."
          },
          "minTimesShown": {
            "title": "Min times shown",
            "minimum": 0,
            "type": "integer",
            "description": "Only political ads shown at least this many times, rounded down to Google's brackets (1,000, 10,000, 50,000, 100,000, 250,000, 500,000, 1M, 2.5M, 5M, 10M). Switches on Political ads."
          },
          "sortBy": {
            "title": "Sort political ads by",
            "enum": [
              "newest",
              "mostSpent",
              "mostShown"
            ],
            "type": "string",
            "description": "The order Google lists political ads in: the newest shown first (as every search), the most spent first, or the most shown first. Max results then keeps the top ones. Most spent or most shown switches on Political ads."
          },
          "politicalSpendSummary": {
            "title": "Political spend summary",
            "type": "boolean",
            "description": "Add one row per region or advertiser with Google's summary of its political spend (the political page's Insights): the total spend and number of ads, their split by format, by state or place and by day, and the top 100 advertisers by spend, in the dates, format and platform asked for. Charged as one result each. Set Max ads per advertiser to 0 for the summaries alone. Switches on Political ads."
          },
          "removedAds": {
            "title": "Removed ads",
            "type": "boolean",
            "description": "Read Google's feed of the ads it removed in Europe (published under the EU's Digital Services Act), newest decision first, up to Max results: each removed ad's policies (name, category, help page, decision by Google's investigation or a legal notice, automated or not, where), when Google decided, and when the ad ran; with ad details, its reach per country and in the EEA and its audience selection. Google doesn't name the advertiser or show the ad. About 20,000 ads are removed a day, published about a month after the decision. With Only changes, only those decided since the last run."
          },
          "removalReasons": {
            "title": "Removal reasons",
            "type": "array",
            "description": "Only ads removed for these policies or categories (the start of a word is enough: 'gambling', 'alcohol', 'financial', 'misrepresentation', 'account suspension', 'prohibited content'). Up to 10,000 removed ads are scanned a run to find them (most are removed for misrepresentation). Switches on Removed ads.",
            "items": {
              "type": "string"
            }
          },
          "onlyChanges": {
            "title": "Only changes since the last run",
            "type": "boolean",
            "description": "Monitor competitors: each run returns only what changed since the last run with the same advertisers and filters (new ads, ads that stopped running, ads running again). The first run saves the ads there now as the baseline and returns them as firstRun."
          },
          "changeTypes": {
            "title": "Changes to return",
            "type": "array",
            "description": "Which changes Only changes returns. Leave empty for all.",
            "items": {
              "type": "string",
              "enum": [
                "newAd",
                "adStopped",
                "adResumed"
              ],
              "enumTitles": [
                "New ads",
                "Ads that stopped running",
                "Ads running again"
              ]
            }
          },
          "alertWebhookUrl": {
            "title": "Alert webhook URL",
            "type": "string",
            "description": "Post each run's changes to Slack, Discord or Microsoft Teams (their incoming-webhook URL), or to any HTTPS endpoint that takes JSON (Zapier, Make, n8n). Switches on Only changes. The first run posts a short 'alerts are set up' message."
          },
          "alertChangeTypes": {
            "title": "Alert on",
            "type": "array",
            "description": "Which changes are posted. Leave empty for new ads and ads that stopped.",
            "items": {
              "type": "string",
              "enum": [
                "newAd",
                "adStopped",
                "adResumed"
              ],
              "enumTitles": [
                "New ads",
                "Ads that stopped running",
                "Ads running again"
              ]
            }
          },
          "historyName": {
            "title": "History name",
            "type": "string",
            "description": "Keep a separate history for this monitor (a-z, 0-9 and hyphens). Leave empty to share the default one: histories are kept per advertiser and filters anyway."
          },
          "proxy": {
            "title": "Proxy",
            "type": "object",
            "description": "Not needed: the Transparency Center answers Apify's servers directly. You can use your own proxies; residential proxies aren't available in this Actor."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}