{ "openapi": "3.0.1", "info": { "title": "Meta Ad Spend Scraper: Advertiser Spend by Country", "description": "Scrape Meta's Ad Library Report, no login or API key: every advertiser of ads about social issues, elections or politics in 205 countries, ranked by spend. Get page name, page ID, disclaimer, amount spent, number of ads and spend by region. JSON, CSV or API; pay per row, monitors bill only changes.", "version": "0.1", "x-build-id": "6aMLjAwAxuLGSWsl7" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation_craft~meta-ad-spend-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation_craft-meta-ad-spend-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/automation_craft~meta-ad-spend-scraper/runs": { "post": { "operationId": "runs-sync-automation_craft-meta-ad-spend-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/automation_craft~meta-ad-spend-scraper/run-sync": { "post": { "operationId": "run-sync-automation_craft-meta-ad-spend-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": { "mode": { "title": "What to get", "enum": [ "advertisers", "report", "regions" ], "type": "string", "description": "advertisers: the ranked list of advertisers by spend (or by ads, page name or disclaimer), with an optional search by name. report: the whole daily report file as rows (every advertiser, and the region tables when switched on). regions: spend by region (state, province, nation) as rows.", "default": "advertisers" }, "countries": { "title": "Countries", "type": "array", "description": "Two letter country codes in any case, or English names: US, GB, CA, AU, IN, BR, and 200 more. One report per country. Leave empty for the United States. The EU countries hold history only: Meta stopped these ads in the EU in October 2025.", "items": { "type": "string" } }, "timePreset": { "title": "Period", "enum": [ "yesterday", "last_7_days", "last_30_days", "last_90_days", "lifelong" ], "type": "string", "description": "The period the spend covers, ending on the report date: yesterday (the day before the report date), the last 7, 30 or 90 days, or lifelong (everything since the report began, 2018 for the US). Leave empty for yesterday." }, "reportDate": { "title": "Report date", "type": "string", "description": "The date of the report to read (YYYY-MM-DD). Meta publishes a report every day, about two days behind today, and serves the last seven report dates. Leave empty for the newest report; every row carries the report date it came from." }, "maxRows": { "title": "Maximum advertiser rows", "minimum": 1, "maximum": 1000000, "type": "integer", "description": "The most Advertiser spend rows this run may deliver (and charge), over all countries and search terms together. When the field is left out, 100 is used. The whole US report holds about 8,000 advertisers a day, 31,000 over 90 days and 524,000 lifelong; one run delivers at most 150,000 rows in all, and a lifelong report at most 150,000 advertiser rows." }, "sortBy": { "title": "Sort the list by", "enum": [ "spend", "ads", "page_name", "disclaimer" ], "type": "string", "description": "The column Meta sorts the list by, highest first: amount spent (default), number of ads, page name or disclaimer. Leave empty for amount spent." }, "searchTerms": { "title": "Search terms", "type": "array", "description": "One advertiser name or disclaimer text per line, for example Planned Parenthood. Meta returns every row whose page name or disclaimer contains the text (any case); each term gets its own free coverage row. A term nobody matches is free. Mode advertisers only.", "items": { "type": "string" } }, "nameMatch": { "title": "Name match", "enum": [ "contains", "exact" ], "type": "string", "description": "Contains (what you get when the field is left empty): every row Meta returns for the term. Exact: only rows whose page name or disclaimer is exactly the term (case and extra spaces ignored); other rows are read, counted and not charged." }, "minSpend": { "title": "Minimum spend", "minimum": 0, "type": "integer", "description": "Only advertisers that spent at least this amount in the report's currency (whole number). Meta reports spends of 100 or less as one bucket, flagged on the row; a minimum above 100 leaves those rows out, free. Modes advertisers and report." }, "includeRegionTotals": { "title": "Add the region totals (mode report)", "type": "boolean", "description": "Also deliver the file's region totals table (spend per state, province or nation) as Region spend rows, read even when maxRows cuts the advertiser table.", "default": false }, "includeRegionAdvertisers": { "title": "Add every advertiser per region (mode report)", "type": "boolean", "description": "Also deliver the file's per region advertiser tables (every advertiser's spend inside each region) as Region spend rows, read even when maxRows cuts the advertiser table. The US file holds about 130,000 such rows a day: set a cap below or a maximum charge on the run.", "default": false }, "maxRegionRows": { "title": "Maximum region rows", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "The most Region spend rows this run may deliver, over all countries together. 0 or left out means no cap (the run's maximum charge still applies). Mode regions, or mode report with region rows switched on." }, "monitorName": { "title": "Monitor name", "type": "string", "description": "A name of your choice, up to 100 characters. The memory it opens belongs to this Actor and remembers up to 60,000 advertiser rows per report; a report or list larger than that is refused with a free row (a search term is not size limited). Modes advertisers and report." }, "includeRaw": { "title": "Include Meta's raw record", "type": "boolean", "description": "Add Meta's own record of each row (the GraphQL node, or the file's fields) under raw.", "default": false } } }, "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 } } } } } } } } } }