{ "openapi": "3.0.1", "info": { "title": "Ad Library Scraper: Facebook, Google and Bing Ads", "description": "Facebook Ads Library scraper plus Google Ads Transparency Center and Microsoft (Bing) Ad Library in one run: search a brand, keyword or domain and get every platform's ads in one table, with advertiser, payer, dates, reach, targeting and creative links.", "version": "0.1", "x-build-id": "1KBSapIcspuriCiug" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/agenttoolworks~ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-agenttoolworks-ad-library-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/agenttoolworks~ad-library-scraper/runs": { "post": { "operationId": "runs-sync-agenttoolworks-ad-library-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/agenttoolworks~ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-agenttoolworks-ad-library-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": { "query": { "title": "Brand or keyword", "type": "string", "description": "What to search. Meta and Microsoft search the ad text and advertiser for this keyword (when Microsoft's keyword search does not answer, Microsoft returns the ads of the advertisers named like it, and the run summary says so). Google has no text search: the Actor finds the Google advertisers whose name contains this word (for example 'nike' finds 'Nike, Inc.' and 'Nike Retail BV') and returns their ads. Optional when startUrls are set." }, "domain": { "title": "Advertiser domain", "type": "string", "description": "Optional. An advertiser's website, for example nike.com. Google returns the ads that point to this domain; Meta and Microsoft search for it as a keyword when no brand or keyword is set." }, "startUrls": { "title": "Meta Ad Library or Facebook Page URLs", "type": "array", "description": "Optional. Paste Meta Ad Library search URLs (every filter you set on Meta's page is kept: keyword, country, active status, ad type, media type, dates), a page's ads URL (view_all_page_id=...), Facebook Page URLs (facebook.com/nike) or page IDs. Each is its own Meta search, up to the max ads below. Meta only: to search Google and Microsoft too, also set a brand or keyword.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "platforms": { "title": "Platforms", "type": "array", "description": "Which ad libraries to search. All three by default; Meta only when you give startUrls and no brand or keyword.", "items": { "type": "string", "enum": [ "meta", "google", "microsoft" ], "enumTitles": [ "Meta (Facebook, Instagram, Messenger, Threads)", "Google (Search, YouTube, Display, Shopping)", "Microsoft (Bing, EEA ads only)" ] }, "default": [ "meta", "google", "microsoft" ] }, "countries": { "title": "Countries", "type": "array", "description": "Two-letter country codes (FR, DE, US...). Empty means all countries. Meta runs one search per country; Microsoft only covers the EEA, so it is skipped when no requested country is in the EEA.", "items": { "type": "string" } }, "maxResultsPerPlatform": { "title": "Max ads per platform", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Stop after this many ads on each platform. You are charged per ad returned.", "default": 100 }, "startDate": { "title": "Shown from", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Optional, YYYY-MM-DD. Only ads shown on or after this day, on every platform." }, "endDate": { "title": "Shown until", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Optional, YYYY-MM-DD. Only ads shown on or before this day, on every platform." }, "activeOnly": { "title": "Active ads only (Meta)", "type": "boolean", "description": "Meta only: return ads running today. Turn off to include ads that stopped (Meta keeps ads shown in the EU for a year after they stop, and political ads for seven years).", "default": true }, "includeDetails": { "title": "Include reach, payer and targeting", "type": "boolean", "description": "One extra request per ad for the transparency details. Meta: EU reach (people reached, per country), payer, beneficiary and audience (locations, ages, gender), for ads shown in the EU. Google: impressions per country, first and last day shown, targeting criteria, and the text of text ads where Google renders it. Microsoft: impressions per country, dates, targeting, payer. Slower; turn off for a fast list of creatives.", "default": true }, "strictMatch": { "title": "Only ads that show the keyword (Meta)", "type": "boolean", "description": "Meta also matches your keyword inside images and videos, and in its 'Most recent' pages beyond the first 30 ads about half of the matches do not show the keyword anywhere in their text. On (the default), such ads are left out before they are returned or charged, and the Actor reads further to fill your request. Off, they are kept and flagged with matchesQuery false.", "default": true }, "maxAdvertisers": { "title": "Advertisers per platform", "minimum": 0, "maximum": 20, "type": "integer", "description": "Optional, off by default. Also return up to this many advertisers matching your search per platform (ID, name, country, ad count where published): the brand's footprint across platforms. They are stored in the run's key-value store (record ADVERTISERS), not in the ads dataset, and charged per advertiser.", "default": 0 }, "proxy": { "title": "Proxy for Meta", "enum": [ "none", "datacenter", "residential" ], "type": "string", "description": "Meta only. No proxy is the fastest and cheapest, and read 1,000 Meta ads in our tests. With a proxy, a page Meta refuses is retried from a new IP. Residential costs about 12 times more in Apify usage. Google and Microsoft always answer directly.", "default": "none" } } }, "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 } } } } } } } } } }