{ "openapi": "3.0.1", "info": { "title": "TikTok Keyword Search Scraper", "description": "TikTok Keyword Search Scraper finds public TikTok posts using targeted keywords and extracts captions, creators, hashtags, views, likes, comments, shares, upload dates, and video URLs. Build structured datasets for trend research, content discovery, and competitor analysis.", "version": "0.1", "x-build-id": "C8jjp5hI7U64eM1hg" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scraper-engine~tiktok-keyword-search-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scraper-engine-tiktok-keyword-search-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/scraper-engine~tiktok-keyword-search-scraper/runs": { "post": { "operationId": "runs-sync-scraper-engine-tiktok-keyword-search-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/scraper-engine~tiktok-keyword-search-scraper/run-sync": { "post": { "operationId": "run-sync-scraper-engine-tiktok-keyword-search-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": [ "queries" ], "properties": { "queries": { "title": "🔎 Search Queries", "type": "array", "description": "One or more keywords/phrases to search for — or paste full TikTok search URLs (https://www.tiktok.com/search?q=...), mixed freely. Each query is scraped independently and results stream into the dataset as they're found.", "items": { "type": "string" } }, "datePosted": { "title": "📅 Date Posted Filter", "enum": [ "today", "this-week", "this-month", "this-year" ], "type": "string", "description": "Only keep videos published within this window. Applied client-side (TikTok's anonymous search API accepts no server-side date filter)." }, "sortBy": { "title": "↕️ Sort Order", "enum": [ "relevance", "date", "views" ], "type": "string", "description": "How to order results. Applied client-side after collection (TikTok's anonymous search API accepts no server-side sort parameter).", "default": "relevance" }, "region": { "title": "🌍 Region", "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "type": "string", "description": "2-letter country code (e.g. US, GB, DE) — sent as an Accept-Language locale hint only. Left empty by default so the automatic proxy fallback isn't constrained to one country's IP pool; for a real change of exit-IP geography, pick a country inside 'Proxy configuration' below instead." }, "maxResults": { "title": "📦 Maximum Results", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Maximum number of videos to fetch per query (0 = nothing, useful for a dry run).", "default": 10 }, "proxyConfiguration": { "title": "🌐 Proxy Configuration", "type": "object", "description": "🟢 Default = no proxy (direct connection), which works for most runs. If TikTok starts rejecting requests, the Actor automatically escalates itself: Direct ➜ 🖥️ Datacenter proxy ➜ 🏠 Residential proxy (retried up to 3×), then stays on residential for the rest of the run. Every switch is logged. Override this only to force a specific proxy from the start." }, "maxMountRetries": { "title": "🔁 Max Page-Load Retries", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many times to reload the search page before treating it as blocked and escalating the proxy. Raise this if runs on a slow connection give up too early.", "default": 5 }, "maxScrollRetries": { "title": "🔁 Max Empty-Scroll Retries", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many consecutive scrolls with no new videos to allow before assuming a query has no more results.", "default": 4 }, "maxScanned": { "title": "🔎 Max Scanned Rows", "minimum": 100, "maximum": 200000, "type": "integer", "description": "Safety cap on how many raw videos a single query may scan through while paginating, even if 'Maximum Results' hasn't been reached yet (protects against a runaway crawl).", "default": 20000 }, "concurrency": { "title": "⚡ Concurrency", "minimum": 1, "maximum": 5, "type": "integer", "description": "How many queries to scrape in parallel browser tabs. Keep this low — TikTok's anti-bot risk system is more likely to challenge a run that looks like a burst of parallel traffic.", "default": 2 } } }, "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 } } } } } } } } } }