{ "openapi": "3.0.1", "info": { "title": "TikTok Search by Keywords", "description": "Search public TikTok videos by keyword, hashtag, country and date range — or fetch specific videos directly from their URLs. Get views, likes, comments, shares, author stats, music and more as clean, structured data.", "version": "1.0", "x-build-id": "H93LxErVdKBkWKF7d" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lofomachines~tiktok-search-by-keywords/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lofomachines-tiktok-search-by-keywords", "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/lofomachines~tiktok-search-by-keywords/runs": { "post": { "operationId": "runs-sync-lofomachines-tiktok-search-by-keywords", "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/lofomachines~tiktok-search-by-keywords/run-sync": { "post": { "operationId": "run-sync-lofomachines-tiktok-search-by-keywords", "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": { "keywords": { "title": "Keywords", "uniqueItems": true, "type": "array", "description": "Words, hashtags, brand names or phrases to find inside TikTok videos. Add one keyword per line (you can paste many at once for bulk search). A video is collected when the keyword appears anywhere in its caption, hashtags, on-screen text or author name, even when joined with other words or symbols (for example, the keyword \"gardening\" also matches \"#gardening\" and \"GardeningTips\"). A keyword made of several words finds videos containing all of those words, wherever they appear — they do not have to sit next to each other, so \"ammiraglio bergotto\" still finds a video captioned \"Ammiraglio di Squadra Giuseppe Berutti Bergotto\". To require an exact phrase instead, wrap the keyword in double quotes. Optional when you provide direct video URLs instead.", "items": { "type": "string" } }, "videoUrls": { "title": "Video URLs (direct mode)", "uniqueItems": true, "type": "array", "description": "Fetch specific TikTok videos directly, skipping keyword search entirely. Add one video URL per line — every video is downloaded in parallel with all its metadata. Accepted format: https://www.tiktok.com/@username/video/1234567890123456789 (photo/slideshow posts with /photo/ work too). Shortened vm.tiktok.com links are not supported. Can be combined with keywords in the same run.", "items": { "type": "string" } }, "maxVideosPerKeyword": { "title": "Max videos per keyword", "minimum": 10, "maximum": 3000, "type": "integer", "description": "How many videos to collect for each keyword. Increase it for broader coverage, lower it for faster and cheaper runs. Not applied to direct video URLs — those are always all fetched. Note: on the Apify free plan a run stops at 10 results in total; upgrade to any paid plan to remove that limit.", "default": 100 }, "strictKeywordMatch": { "title": "Only keep videos whose caption contains the keyword", "type": "boolean", "description": "Off by default, so you get every video the search finds. TikTok pages also show other videos by the same creator, so the search sometimes returns a video whose own caption does not repeat your keyword — those are kept too, which typically means around two and a half times more results for the same run. Turn this on for a smaller, stricter dataset in which every row mentions your keyword in its caption, hashtags, on-screen text or creator name.", "default": false }, "country": { "title": "Target country", "pattern": "^[A-Za-z]{2}$", "type": "string", "description": "Two-letter country code of the market you want to target, e.g. \"us\" (United States), \"it\" (Italy), \"gb\" (United Kingdom), \"de\" (Germany), \"fr\" (France), \"es\" (Spain), \"br\" (Brazil), \"in\" (India). Results and language are tuned to this market. Only used for keyword search — direct video URLs ignore it.", "default": "us" }, "publishedAfter": { "title": "Posted after (optional)", "type": "string", "description": "Only collect videos published on or after this date. Enforced against each video's exact publication time. Leave both date fields empty to automatically search the most recent videos first." }, "publishedBefore": { "title": "Posted before (optional)", "type": "string", "description": "Only collect videos published on or before this date. Enforced against each video's exact publication time. Leave both date fields empty to automatically search the most recent videos first." } } }, "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 } } } } } } } } } }