{ "openapi": "3.0.1", "info": { "title": "TikTok Video & Comments Scraper", "description": "Extract public TikTok video metadata, comments and replies. Optional downloads, speech transcription and experimental AI captions. Bounded profile samples; source limitations are reported.", "version": "0.2", "x-build-id": "isfYaJ2ZP1e5ajRnB" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/peerless_columbine~tiktok-video-scraper-independent/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-peerless_columbine-tiktok-video-scraper-independent", "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/peerless_columbine~tiktok-video-scraper-independent/runs": { "post": { "operationId": "runs-sync-peerless_columbine-tiktok-video-scraper-independent", "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/peerless_columbine~tiktok-video-scraper-independent/run-sync": { "post": { "operationId": "run-sync-peerless_columbine-tiktok-video-scraper-independent", "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": { "postURLs": { "title": "Direct URL(s) for scraping specific video(s)", "minItems": 0, "maxItems": 100, "type": "array", "description": "Canonical video/photo URLs, public vm/vt or /t/ share links, or decimal video IDs. Empty is allowed with another discovery input.", "items": { "type": "string" }, "default": [ "https://www.tiktok.com/@apifylife/video/7200360993149553925" ] }, "scrapeRelatedVideos": { "title": "Scrape related videos", "type": "boolean", "description": "Request the ordinary public related-video list for each direct video. Empty or blocked source responses fail explicitly.", "default": false }, "resultsPerPage": { "title": "Videos per profile, hashtag, search or related input", "minimum": 1, "maximum": 1000000, "type": "integer", "description": "Per-discovery-input output cap. Direct input URLs are not truncated. Global profile sorting requires a complete verified source list.", "default": 1 }, "shouldDownloadVideos": { "title": "Store video files", "type": "boolean", "description": "Store each accessible video file in KVS. Delivered downloads incur the video-download add-on shown in Pricing; platform usage is included.", "default": false }, "shouldDownloadCovers": { "title": "Include thumbnails", "type": "boolean", "description": "Tick to download TikTok video cover images (thumbnails). Note that this will increase time and costs needed to extract the data.", "default": false }, "downloadSubtitlesOptions": { "title": "Subtitles & Transcription", "enum": [ "NEVER_DOWNLOAD_SUBTITLES", "DOWNLOAD_SUBTITLES", "DOWNLOAD_AND_TRANSCRIBE_VIDEOS_WITHOUT_SUBTITLES", "TRANSCRIBE_ALL_VIDEOS" ], "type": "string", "description": "Download source subtitles or CPU transcription. Transcription is billed per started minute per delivered video. Set cloud memory to 1024 MB for ASR.", "default": "NEVER_DOWNLOAD_SUBTITLES" }, "shouldDownloadSlideshowImages": { "title": "Download slideshow images", "type": "boolean", "description": "Tick to download TikTok slideshow images. Note that this will increase costs and time required for scraping.", "default": false }, "videoKvStoreIdOrName": { "title": "✍️ Name your storage for videos", "pattern": "^[a-zA-Z0-9-]+$", "type": "string", "description": "Optional existing or named KVS for media. Omit for the default KVS. Platform retention rules apply; no permanent-storage promise." }, "allowPartialResults": { "title": "Keep real rows when an optional media download fails", "type": "boolean", "description": "Failure remains visible in coverage and SUMMARY. The run remains incomplete.", "default": false }, "dnsResolver": { "title": "DNS resolver", "enum": [ "system", "google-doh" ], "type": "string", "description": "System DNS by default; explicit public DoH option for local synthetic DNS. Address and TLS checks remain enforced.", "default": "system" }, "maxConcurrency": { "title": "Concurrent video requests", "minimum": 1, "maximum": 10, "type": "integer", "description": "Maximum simultaneous video targets; source requests share a global pacing interval.", "default": 2 }, "maxRequests": { "title": "Source request ceiling", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Global source-request ceiling including redirects and media; reaching it makes the run incomplete.", "default": 50 }, "maxRunSeconds": { "title": "Collection deadline", "minimum": 10, "maximum": 3600, "type": "integer", "description": "Graceful collection deadline; keep the platform timeout larger to persist the summary.", "default": 100 }, "requestTimeoutSeconds": { "title": "Request timeout", "minimum": 1, "maximum": 60, "type": "integer", "description": "Finite source socket deadline, clamped by remaining collection time.", "default": 15 }, "requestIntervalMillis": { "title": "Minimum request spacing (ms)", "minimum": 200, "maximum": 10000, "type": "integer", "description": "Minimum interval between sequential request starts in milliseconds.", "default": 500 }, "maxRetries": { "title": "Transient retries", "minimum": 0, "maximum": 2, "type": "integer", "description": "Bounded retries for network failures and ordinary 5xx. Never retries access denials or challenges.", "default": 1 }, "maxMediaBytes": { "title": "Maximum bytes per media file", "minimum": 1000, "maximum": 50000000, "type": "integer", "description": "Maximum stored bytes for each media file; oversize files fail explicitly.", "default": 10000000 }, "saveSourceEvidence": { "title": "Save public page evidence", "type": "boolean", "description": "Save public metadata pages/comment API bytes as SOURCE-* Base64 JSON. When AI analysis is enabled, also save source MP4 and decoded sample PNGs for independent readback.", "default": false }, "commentsPerPost": { "title": "Maximum comments per video (including replies)", "minimum": 0, "maximum": 5000, "type": "integer", "description": "Zero keeps video-only behavior. Positive values collect public comments; replies share this total per-video limit.", "default": 0 }, "maxRepliesPerComment": { "title": "Maximum replies per top-level comment", "minimum": 0, "maximum": 1000, "type": "integer", "description": "Zero collects only top-level comments. Positive values traverse reply pages and retain immediate-parent plus root-thread IDs.", "default": 0 }, "topLevelCommentsPerPost": { "title": "Maximum top-level comments per video", "minimum": 0, "maximum": 5000, "type": "integer", "description": "Optional additional top-level cap. Defaults to commentsPerPost when omitted." }, "commentsOnly": { "title": "Output comments as Dataset rows", "type": "boolean", "description": "Requires commentsPerPost above zero. Each Dataset row is a comment or reply; media-download options must be off. Otherwise videos retain a nested comments list.", "default": false }, "commentPageSize": { "title": "Comment page size", "minimum": 1, "maximum": 20, "type": "integer", "description": "Requested page size for both comment and reply pages. Source cursors, rather than returned row counts, drive pagination.", "default": 20 }, "maxConsecutiveEmptyCommentPages": { "title": "Maximum consecutive comment pages without new results", "minimum": 0, "maximum": 10, "type": "integer", "description": "Follow advancing source cursors through sparse or duplicate-only pages, with this finite no-progress bound. Zero rejects the first such page. Request and time budgets also apply.", "default": 3 }, "hashtags": { "title": "#️⃣ Videos with this hashtag", "maxItems": 100, "type": "array", "description": "Optional public hashtag discovery. This source is currently unreliable and can fail with DISCOVERY_SOURCE_UNAVAILABLE. Leave empty for direct video/comment collection.", "items": { "type": "string" }, "default": [] }, "profiles": { "title": "Usernames", "maxItems": 100, "type": "array", "description": "Add one or multiple TikTok usernames or user IDs you want to scrape. You can enter the usernames one by one, or use the Bulk edit section to add a prepared list.", "items": { "type": "string" }, "default": [] }, "profileScrapeSections": { "title": "Profile sections to scrape", "minItems": 1, "uniqueItems": true, "type": "array", "description": "Videos supported by structured public profile lists. Reposts/stories remain explicit unsupported gaps.", "items": { "type": "string", "enum": [ "videos", "reposts", "stories" ], "enumTitles": [ "Videos", "Reposts", "Stories" ] }, "default": [ "videos" ] }, "profileSorting": { "title": "Profile video sorting", "enum": [ "latest", "popular", "oldest" ], "type": "string", "description": "Select Latest to scrape the most recent videos first, Oldest - the oldest videos first, Popular - the most popular videos first. Date filters only work with Latest and Oldest. Only supported for Videos section. Note: Popular sorting is limited by TikTok to approximately 400–500 videos per profile and may return significantly fewer results than Latest or Oldest.", "default": "latest" }, "excludePinnedPosts": { "title": "Exclude pinned posts", "type": "boolean", "description": "Tick to exclude pinned posts from profiles. Pinned posts are usually the first videos on a profile's page.", "default": false }, "oldestPostDateUnified": { "title": "📅 Date filter - scrape profile videos published after [date] ($)", "pattern": "^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])(T[0-2]\\d:[0-5]\\d(:[0-5]\\d)?(\\.\\d+)?Z?)?$|^(\\d+)\\s*(minute|hour|day|week|month|year)s?$", "type": "string", "description": "Optional filter. Only videos uploaded after or on this date will be scraped. Alternatively, specify how old the scraped videos should be in days. Putting 1 will get you only today's posts, 2 - yesterday's and today's, and so on." }, "newestPostDate": { "title": "📅 Date filter - scrape profile videos published before [date] ($)", "type": "string", "description": "Optional filter. Only videos uploaded before or on this date will be scraped." }, "mostDiggs": { "title": "⭐ Popularity filter - scrape videos with number of hearts < [number] ($)", "minimum": 1, "type": "integer", "description": "Optional filter. Scrapes only videos with less hearts than the number you add. Doesn't work with date filters" }, "leastDiggs": { "title": "⭐ Popularity filter - scrape videos with number of hearts ≥ [number] ($)", "minimum": 1, "type": "integer", "description": "Optional filter. Scrapes only videos with no less hearts than the number you add. Doesn't work with date filters" }, "maxFollowersPerProfile": { "title": "🗂️ Maximum number of followers profiles ($)", "minimum": 0, "maximum": 5000, "type": "integer", "description": "Reserved competitor option; nonzero is rejected because social-list acquisition is not implemented.", "default": 0 }, "maxFollowingPerProfile": { "title": "🗂️ Maximum number of following profiles ($)", "minimum": 0, "maximum": 5000, "type": "integer", "description": "Reserved competitor option; nonzero is rejected because social-list acquisition is not implemented.", "default": 0 }, "searchQueries": { "title": "Search queries", "maxItems": 100, "type": "array", "description": "Your keyword will apply to both videos and profiles. Use the Search sorting field below to specify whether you want your search to apply to top content, videos or users.
As for your query's format, you can use any query that works on TikTok.", "items": { "type": "string" }, "default": [] }, "searchSection": { "title": "Top/Video/Profile section", "enum": [ "", "/video", "/user" ], "type": "string", "description": "By default, this scraper will sort the search results by whatever shows up in the Top section of TikTok search.
But you can narrow it down: if you want to apply your search query to just videos, use Video, just profiles - Profile.", "default": "" }, "maxProfilesPerQuery": { "title": "Number of profiles per query", "minimum": 1, "type": "integer", "description": "Only applies to profile searches. In this case ignore the 💯 Number of videos section and choose the number of profiles you want to scrape here.", "default": 10 }, "videoSearchSorting": { "title": "🎯 Video search sorting ($)", "enum": [ "MOST_RELEVANT", "MOST_LIKED", "LATEST" ], "type": "string", "description": "Optional filter. Select how you want the search results to be sorted when searching for videos. Only valid with `/video` search section.", "default": "MOST_RELEVANT" }, "videoSearchDateFilter": { "title": "📅 Video search date filter ($)", "enum": [ "ALL_TIME", "PAST_24_HOURS", "PAST_WEEK", "PAST_MONTH", "LAST_3_MONTHS", "LAST_6_MONTHS" ], "type": "string", "description": "Optional filter. Select a date range in which to search for videos. Only valid with `/video` search section.", "default": "ALL_TIME" }, "scrapeRelatedSearchWords": { "title": "Scrape related search words", "type": "boolean", "description": "Tick to include the keywords TikTok shows in the 'Others also searched for' section on the search results page. The words will be added to every video result.", "default": false }, "scrapeAdditionalAuthorMeta": { "title": "Scrape additional author profile metadata", "type": "boolean", "description": "Tick to fetch full author profile data (createTime, roomId) for each scraped video. Note: when scraping by profile URL, this data is already included by default — this option only makes a difference for other search types (e.g. hashtags, keywords).", "default": false }, "shouldDownloadAvatars": { "title": "Include profile avatars", "type": "boolean", "description": "Store source-provided images in KVS.", "default": false }, "shouldDownloadMusicCovers": { "title": "Include sound covers", "type": "boolean", "description": "Store source-provided images in KVS.", "default": false }, "aiVideoDescription": { "title": "AI video description", "type": "boolean", "description": "CPU-generated English descriptions for time windows represented by sampled real video frames, with recognized speech. Stored under videoMeta.aiVideoDescription; aiAnalysisEvidence states sampling and unbenchmarked accuracy. Requires 2048 MB, public model download and sufficient deadline. No external inference API.", "default": false }, "aiVideoSummary": { "title": "AI video summary", "type": "boolean", "description": "CPU-generated English summary of sampled frame descriptions and recognized speech under videoMeta.aiVideoSummary. Requires 2048 MB. Full scene coverage and quality parity are not guaranteed.", "default": false }, "proxyCountryCode": { "title": "Scraping exit country", "enum": [ "None", "AF", "AL", "DZ", "AS", "AD", "AO", "AI", "AG", "AR", "AM", "AU", "AT", "AZ", "BS", "BH", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BA", "BW", "BR", "VG", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "TD", "CL", "CO", "CK", "CR", "HR", "CY", "CZ", "CD", "DK", "DJ", "DO", "EC", "EG", "SV", "EE", "ET", "FK", "FJ", "FI", "FR", "PF", "GA", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GT", "GN", "GW", "GY", "HN", "HU", "IS", "ID", "IQ", "IE", "IM", "IL", "IT", "CI", "JM", "JP", "JE", "KZ", "KE", "XK", "KW", "LA", "LV", "LB", "LS", "LR", "LY", "LT", "LU", "MO", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "MX", "MD", "MC", "MN", "ME", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NZ", "NI", "NG", "MK", "NO", "OM", "PS", "PA", "PG", "PY", "PE", "PH", "PL", "PT", "PR", "QA", "CG", "RO", "RU", "RW", "RE", "KN", "LC", "MF", "PM", "VC", "SM", "SA", "SN", "RS", "SL", "SG", "SX", "SK", "SB", "SO", "ZA", "KR", "ES", "LK", "SR", "SZ", "SE", "CH", "TW", "TJ", "TZ", "TH", "TG", "TO", "TT", "TN", "TR", "TC", "TV", "VI", "UG", "UA", "AE", "GB", "US", "UY", "VE", "VN", "WF", "YE", "ZM", "ZW", "AX" ], "type": "string", "description": "Network exit country, not author/commenter nationality or a content-country filter. None with no proxyConfiguration preserves direct requests. A country alone selects Apify RESIDENTIAL. Availability depends on proxy permissions and live exits; failed verification stops without direct/other-country fallback.", "default": "None" }, "emitErrorRows": { "title": "Include competitor-style error items", "type": "boolean", "description": "Write errorCode/input/url/error records to the Dataset. SUMMARY also retains stage and coverage details.", "default": true }, "commentsOutputMode": { "title": "Comment storage", "enum": [ "nested", "separate" ], "type": "string", "description": "Nested comment arrays preserve existing video output. Separate writes comments to a second Dataset and returns commentsDatasetUrl. commentsOnly still writes flat rows to the main Dataset.", "default": "nested" }, "maxPagesPerDiscovery": { "title": "Maximum pages per discovery input", "minimum": 1, "maximum": 100, "type": "integer", "description": "Bound profile/list traversal. Hitting this bound does not establish source exhaustion or global sorting.", "default": 20 }, "maxDiscoveredVideos": { "title": "Maximum discovered video IDs", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Per-input safety ceiling on discovery enumeration, before sorting/filtering.", "default": 500 }, "asrModel": { "title": "Local speech model", "enum": [ "tiny", "base" ], "type": "string", "description": "Public faster-whisper model downloaded on first transcription. Runs on CPU with int8; no external inference API.", "default": "tiny" }, "asrLanguage": { "title": "Speech language", "pattern": "^[a-z]{2,3}$", "type": "string", "description": "Optional language code; omit for model detection." }, "maxTranscriptionSeconds": { "title": "Maximum video duration for transcription", "minimum": 1, "maximum": 300, "type": "integer", "description": "Reject longer videos before model inference; inference shares the collection deadline.", "default": 60 }, "maxVisualSeconds": { "title": "Maximum video duration for AI analysis", "minimum": 1, "maximum": 120, "type": "integer", "description": "Checks both source metadata and decoded MP4 duration. Analysis shares the run deadline.", "default": 60 }, "visualFrameCount": { "title": "Sampled frames for AI analysis", "minimum": 0, "maximum": 128, "type": "integer", "description": "0 (default) scans the whole decoded video, samples at the configured interval, includes first/last frames and detected hard cuts. Positive values preserve legacy uniform fixed-count sampling. No guarantee of every scene or model accuracy.", "default": 0 }, "visualSampleIntervalSeconds": { "title": "AI maximum regular sampling interval", "minimum": 1, "maximum": 5, "type": "integer", "description": "Timeline mode samples at this interval plus detected cuts and endpoints; decode timestamp gaps are checked. Not an every-frame semantic analysis.", "default": 1 }, "maxVisualFrames": { "title": "AI sampled-frame ceiling", "minimum": 8, "maximum": 256, "type": "integer", "description": "Fail explicitly if timeline samples and detected cuts exceed this budget; do not silently discard coverage.", "default": 128 }, "profileDiscoveryMode": { "title": "Profile acquisition scope", "enum": [ "complete", "public-recent-sample" ], "type": "string", "description": "Complete retains full enumeration/global filter semantics. Public recent sample reads only the official creator embed selection (up to 10, often fewer), with observed-only latest sorting and no date/pin/like filters; full profile parity is not claimed.", "default": "complete" }, "proxyConfiguration": { "title": "Apify Proxy (optional)", "type": "object", "description": "Omit for direct requests when country is None. Country alone enables RESIDENTIAL. Advanced users can select authorized residential or ordinary datacenter groups. Conflicting/disabled country settings or custom proxy URLs are rejected. All TikTok source/media requests share one session per run." } } }, "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 } } } } } } } } } }