{ "openapi": "3.0.1", "info": { "title": "🌟 X (Twitter) Ads Transparency Scraper", "description": "Scrape X/Twitter ads from the Ads Transparency Center. Covers political, issue, commercial archives and the live DSA Ads Repository for current EU ads. Filter by advertiser, keyword, or location. Export to HTML, JSON, CSV, or Excel. Get webhook notifications for new campaigns.", "version": "1.0", "x-build-id": "eqml6sDpLim6eCNF2" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/databuddy~x-ads-transparency-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-databuddy-x-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/databuddy~x-ads-transparency-scraper/runs": { "post": { "operationId": "runs-sync-databuddy-x-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/databuddy~x-ads-transparency-scraper/run-sync": { "post": { "operationId": "run-sync-databuddy-x-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", "required": [ "sources" ], "properties": { "sources": { "title": "Data Sources", "type": "array", "description": "Which ad archives to scrape. 'political' and 'issue' are 2018-2019 US archives. 'commercial' is the Dec 2023 promoted tweet snapshot. 'dsa' is the live EU DSA Ads Repository (requires X API bearer token).", "items": { "type": "string", "enum": [ "political", "issue", "commercial", "dsa" ] }, "default": [ "political" ] }, "advertisers": { "title": "Advertiser Filter", "type": "array", "description": "Filter ads by advertiser handle or name. Case-insensitive substring match. Leave empty for all advertisers.", "items": { "type": "string" }, "default": [] }, "keyword": { "title": "Keyword Filter", "type": "string", "description": "Search keyword to match against ad text, advertiser name/handle, agency, and reported URLs. Case-insensitive.", "default": "" }, "location": { "title": "Location Filter", "type": "string", "description": "Filter ads by geographic targeting location (e.g. 'United States', 'California', 'New York'). Matches against targeting geo values. Case-insensitive.", "default": "" }, "startDate": { "title": "Start Date", "type": "string", "description": "Only include ads created on or after this date (YYYY-MM-DD).", "default": "" }, "endDate": { "title": "End Date", "type": "string", "description": "Only include ads created on or before this date (YYYY-MM-DD).", "default": "" }, "minSpendUsd": { "title": "Minimum Spend (USD)", "minimum": 0, "type": "integer", "description": "Only include ads with total spend >= this amount. Applies to political/issue sources only." }, "minImpressions": { "title": "Minimum Impressions", "minimum": 0, "type": "integer", "description": "Only include ads with total impressions >= this amount. Applies to political/issue sources only." }, "maxItems": { "title": "Max Results", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Maximum number of ad records to return across all sources.", "default": 1000 }, "hydrateTweets": { "title": "Hydrate Tweets (Commercial)", "type": "boolean", "description": "For commercial archive: fetch full tweet data (engagement, media) from X's syndication endpoint.", "default": false }, "dsaAdvertiserUserId": { "title": "DSA Advertiser User ID", "type": "string", "description": "X user ID of the advertiser to look up in the DSA repository. Required when 'dsa' source is selected.", "default": "" }, "dsaCountry": { "title": "DSA Country", "type": "string", "description": "ISO country code for DSA repository query (e.g. 'DE', 'FR', 'IT'). Defaults to all EU countries.", "default": "" }, "bearerToken": { "title": "X API Bearer Token", "type": "string", "description": "Bearer token from your X Developer account. Required for DSA repository access." }, "exportFormat": { "title": "Export Format", "enum": [ "none", "html", "excel" ], "type": "string", "description": "Additional export format saved to key-value store. Dataset always available as JSON/CSV. Choose 'html' or 'excel' for extra exports.", "default": "none" }, "webhookUrl": { "title": "Webhook URL", "type": "string", "description": "URL to POST new ad records to. Use for notifications when new campaigns match your filters. Each new ad is sent as a JSON payload.", "default": "" }, "maxConcurrency": { "title": "Max Concurrency", "minimum": 1, "maximum": 50, "type": "integer", "description": "Maximum parallel requests for tweet hydration and live checks.", "default": 10 }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Optional proxy settings. Rarely needed for archive downloads." } } }, "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 } } } } } } } } } }