{ "openapi": "3.0.1", "info": { "title": "TikTok Ad Library Scraper - Fast & Reliable", "description": "Scrape TikTok ads in seconds. Extract ad creatives, video URLs, targeting data (age, gender), reach estimates, advertiser info, and \"paid for by\" details from the TikTok Ad Library. Ideal for ad intelligence, competitor research, and marketing analytics. Clean JSON output.", "version": "0.0", "x-build-id": "QQ5f2AVbGnm7i4pyu" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/whoareyouanas~tiktok-ad-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-whoareyouanas-tiktok-ad-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/whoareyouanas~tiktok-ad-scraper/runs": { "post": { "operationId": "runs-sync-whoareyouanas-tiktok-ad-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/whoareyouanas~tiktok-ad-scraper/run-sync": { "post": { "operationId": "run-sync-whoareyouanas-tiktok-ad-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": { "scrapeMode": { "title": "Scrape Mode", "enum": [ "ad_library", "creative_center", "both" ], "type": "string", "description": "Choose which TikTok data source to scrape. Ad Library covers EU/EEA with rich targeting data. Creative Center covers 50+ countries globally with performance metrics. 'Both' runs both sources.", "default": "ad_library" }, "targetUrl": { "title": "Direct URL (Optional)", "type": "string", "description": "Paste a TikTok Ad Library or Creative Center URL directly. If provided, all parameter fields below are ignored." }, "searchQuery": { "title": "Search Query", "type": "string", "description": "Keyword or advertiser name to search for (e.g. 'nike', 'shopify', 'gaming app')." }, "advertiserId": { "title": "Advertiser Business ID", "type": "string", "description": "TikTok advertiser business ID to look up all ads from a specific advertiser." }, "country": { "title": "Country / Region", "enum": [ "all", "US", "GB", "DE", "FR", "IT", "ES", "NL", "PL", "BE", "SE", "AT", "DK", "FI", "IE", "PT", "CZ", "RO", "HU", "SK", "BG", "HR", "LT", "SI", "LV", "EE", "CY", "LU", "MT", "GR", "CH", "NO", "IS", "LI", "JP", "KR", "AU", "BR", "MX", "IN", "ID", "TH", "VN", "PH", "MY", "SG", "TW", "CA", "AR", "CL", "CO", "PE", "EG", "SA", "AE", "TR", "ZA", "NG", "KE" ], "type": "string", "description": "Country code for filtering. For Ad Library: EU/EEA countries only (e.g. DE, FR, IT, ES, NL, GB). For Creative Center: any of 50+ countries (e.g. US, JP, BR, IN).", "default": "all" }, "industry": { "title": "Industry (Creative Center only)", "enum": [ "all", "apparel_and_accessories", "beauty_and_personal_care", "ecommerce", "education", "finance", "food_and_beverage", "games", "health", "home_improvement", "news_and_entertainment", "tech_and_electronics", "travel", "vehicle" ], "type": "string", "description": "Filter by industry vertical. Only applies to Creative Center mode.", "default": "all" }, "objective": { "title": "Campaign Objective (Creative Center only)", "enum": [ "all", "app_install", "traffic", "lead_generation", "conversions", "reach", "video_views", "community_interaction" ], "type": "string", "description": "Filter by campaign objective. Only applies to Creative Center mode.", "default": "all" }, "timePeriod": { "title": "Time Period", "enum": [ "7", "30", "180" ], "type": "string", "description": "Time window for results. For Ad Library: custom date range via startDate/endDate. For Creative Center: preset windows.", "default": "30" }, "startDate": { "title": "Start Date (Ad Library only)", "type": "string", "description": "Start date for Ad Library search in YYYY-MM-DD format. Defaults to 1 year ago." }, "endDate": { "title": "End Date (Ad Library only)", "type": "string", "description": "End date for Ad Library search in YYYY-MM-DD format. Defaults to today." }, "sortBy": { "title": "Sort By", "enum": [ "last_shown_date_newest", "last_shown_date_oldest", "published_date_newest", "published_date_oldest", "unique_users_high", "unique_users_low", "reach", "ctr", "likes" ], "type": "string", "description": "Sort order for results.", "default": "last_shown_date_newest" }, "quickSearch": { "title": "Quick Search Mode", "type": "boolean", "description": "If enabled, skips detail page visits for faster, cheaper scraping. Returns search-level fields only (no targeting or detailed reach data). Recommended for large-volume scrapes.", "default": false }, "maxResults": { "title": "Max Results", "minimum": 0, "maximum": 10000, "type": "integer", "description": "Maximum number of ads to return. Set to 0 for unlimited. Ad Library has a platform cap of ~3,600 results per query.", "default": 100 }, "maxConcurrency": { "title": "Max Concurrency", "minimum": 1, "maximum": 5, "type": "integer", "description": "Number of parallel requests. Keep at 1 for stability. Increase to 2-3 only if you need faster scraping.", "default": 1 }, "requestHandlerTimeoutSecs": { "title": "Page Timeout (seconds)", "minimum": 60, "maximum": 900, "type": "integer", "description": "Maximum time to wait for scraping to complete per page.", "default": 300 }, "proxyUrl": { "title": "Your Proxy URL (Recommended)", "type": "string", "description": "Residential proxy URL for reliable scraping. Format: http://groups-RESIDENTIAL:YOUR_APIFY_TOKEN@proxy.apify.com:8000. TikTok aggressively blocks datacenter IPs. External proxies (BrightData, Oxylabs) also supported." } } }, "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 } } } } } } } } } }