{ "openapi": "3.0.1", "info": { "title": "TikTok Trends Scraper: TikTok Creative Center Hashtags, Top Ads", "description": "Scrape TikTok Creative Center trends: TikTok trending hashtags in 27 countries over 7, 30 or 90 days with every industry list, TikTok trending videos with weekly and monthly rankings and comments, and TikTok Top Ads with details. A TikTok ads scraper with exact numbers. No login.", "version": "0.1", "x-build-id": "544QU6t89x8binMhw" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/hyperbach~tiktok-creative-center-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-hyperbach-tiktok-creative-center-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/hyperbach~tiktok-creative-center-scraper/runs": { "post": { "operationId": "runs-sync-hyperbach-tiktok-creative-center-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/hyperbach~tiktok-creative-center-scraper/run-sync": { "post": { "operationId": "run-sync-hyperbach-tiktok-creative-center-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": { "sections": { "title": "What to scrape", "type": "array", "description": "The Creative Center lists to read, in one run and one row shape (`section` says which). Empty = trending hashtags, unless you give startUrls, adIds or the Spotlight. Songs, creators, Top Products and Keyword Insights are gone from TikTok's Creative Center: asking for one checks its old route on the run and returns a free labelled row with TikTok's answer, never an empty success.", "items": { "type": "string", "enum": [ "hashtags", "videos", "topAds", "songs", "creators", "products", "keywordInsights" ], "enumTitles": [ "Trending hashtags", "Top videos", "Top Ads", "Songs (TikTok removed this list)", "Creators (TikTok removed this list)", "Top Products (TikTok removed this list)", "Keyword Insights (TikTok removed this list)" ] }, "default": [] }, "hashtagCountries": { "title": "Hashtag countries", "type": "array", "description": "The 27 markets the Creative Center ranks hashtags in. Each country × period is its own set of lists.", "items": { "type": "string", "enum": [ "ALL", "AR", "AU", "BR", "CA", "CO", "EG", "FR", "DE", "ID", "IL", "IT", "JP", "MY", "MX", "PH", "SA", "SG", "ZA", "KR", "ES", "TW", "TH", "TR", "AE", "GB", "US", "VN" ], "enumTitles": [ "All 27 countries", "Argentina", "Australia", "Brazil", "Canada", "Colombia", "Egypt", "France", "Germany", "Indonesia", "Israel", "Italy", "Japan", "Malaysia", "Mexico", "Philippines", "Saudi Arabia", "Singapore", "South Africa", "South Korea", "Spain", "Taiwan", "Thailand", "Turkey", "United Arab Emirates", "United Kingdom", "United States", "Vietnam" ] }, "default": [ "US" ] }, "hashtagPeriods": { "title": "Hashtag periods", "type": "array", "description": "Ranking windows. TikTok ranks hashtags over 7, 30 or 90 days (120 and 180 are gone).", "items": { "type": "string", "enum": [ "7", "30", "90" ], "enumTitles": [ "Last 7 days", "Last 30 days", "Last 90 days" ] }, "default": [ "7" ] }, "hashtagIndustries": { "title": "Hashtag lists", "type": "array", "description": "Empty = every list: the overall ranking plus each of the 15 industry rankings, merged into one row per hashtag with its rank in each (`lists`). Logged out, TikTok shows 3 hashtags per list, so the full sweep gives about 46 hashtags per country and period instead of 3. Pick lists to read only those.", "items": { "type": "string", "enum": [ "Overall", "Education", "Vehicle & Transportation", "Baby, Kids & Maternity", "Beauty & Personal Care", "Tech & Electronics", "Travel", "Household Products", "Pets", "Home Improvement", "Apparel & Accessories", "News & Entertainment", "Games", "Food & Beverage", "Sports & Outdoor", "Health" ], "enumTitles": [ "Overall (all industries)", "Education", "Vehicle & Transportation", "Baby, Kids & Maternity", "Beauty & Personal Care", "Tech & Electronics", "Travel", "Household Products", "Pets", "Home Improvement", "Apparel & Accessories", "News & Entertainment", "Games", "Food & Beverage", "Sports & Outdoor", "Health" ] }, "default": [] }, "hashtags": { "title": "Watch these hashtags", "type": "array", "description": "Keep only these hashtags (`#skincare`, `skincare`, or a tiktok.com/tag/ link). A watched hashtag that is not in TikTok's logged-out lists for a country and period comes back as a free `not_listed` row.", "items": { "type": "string", "pattern": "^(#?[^\\s#]{1,150}|https?://(www\\.)?tiktok\\.com/tag/\\S+)$" }, "default": [] }, "minPosts": { "title": "Minimum posts", "minimum": 0, "maximum": 1000000000, "type": "integer", "description": "Keep hashtags with at least this many posts in the period. 0 = all.", "default": 0 }, "minViews": { "title": "Minimum views", "minimum": 0, "maximum": 1000000000000, "type": "integer", "description": "Keep hashtags with at least this many views in the period. 0 = all.", "default": 0 }, "onlyRising": { "title": "Only rising hashtags", "type": "boolean", "description": "Keep hashtags whose popularity curve is rising (`trend_direction: up`).", "default": false }, "videoCountries": { "title": "Video countries", "type": "array", "description": "The five markets the Creative Center ranks videos in.", "items": { "type": "string", "enum": [ "ALL", "US", "JP", "VN", "TH", "ID" ], "enumTitles": [ "All 5 countries", "United States", "Japan", "Vietnam", "Thailand", "Indonesia" ] }, "default": [ "US" ] }, "videoPeriods": { "title": "Video rankings", "type": "array", "description": "The rolling 7 / 30-day windows, or TikTok's weekly and monthly rankings. Every row carries the window's start and end dates (`period_start`, `period_end`).", "items": { "type": "string", "enum": [ "last_7_days", "last_30_days", "weekly", "monthly" ], "enumTitles": [ "Last 7 days", "Last 30 days", "Weekly ranking (Monday to Sunday)", "Monthly ranking (calendar month)" ] }, "default": [ "last_7_days" ] }, "videoSortBy": { "title": "Video sorts", "type": "array", "description": "Empty = all three. Each sort is its own list of 4 (logged out).", "items": { "type": "string", "enum": [ "views", "engagement_rate", "six_second_view_rate" ], "enumTitles": [ "Views", "Engagement rate", "6-second view-through rate" ] }, "default": [] }, "videoContentTags": { "title": "Video content tags", "type": "array", "description": "Empty = all content plus each of the 13 content tags (the 5 the page offers and 8 more TikTok serves). Each is its own list.", "items": { "type": "string", "enum": [ "All", "Beauty & Care", "Fashion", "Food & Beverage", "Lifestyle & Leisure", "Technology & Finance", "Nature & Animals", "Music & Entertainment", "Games", "Sports & Outdoor", "Family & Relationship", "Vlog & Selfie", "Society", "Vehicles & Transportation" ], "enumTitles": [ "All content", "Beauty & Care", "Fashion", "Food & Beverage", "Lifestyle & Leisure", "Technology & Finance", "Nature & Animals", "Music & Entertainment", "Games", "Sports & Outdoor", "Family & Relationship", "Vlog & Selfie", "Society", "Vehicles & Transportation" ] }, "default": [] }, "videoOrganic": { "title": "Organic views", "enum": [ "both", "all_views", "organic_only" ], "type": "string", "description": "TikTok ranks videos on all views or on organic views only; `both` reads both lists.", "default": "both" }, "videoSnapshots": { "title": "Snapshots back", "minimum": 1, "maximum": 60, "type": "integer", "description": "How many rankings to read per country and period, newest first: 12 with the weekly ranking = the last 12 weeks. TikTok keeps weekly rankings back to 2025-07-27, monthly to 2025-05-31, the rolling windows about 31 days; an end it does not keep comes back as a free `no_snapshot` row.", "default": 1 }, "videoSnapshotDates": { "title": "Snapshot dates", "type": "array", "description": "Read the rankings that hold these dates (YYYY-MM-DD) instead: the week ending on the Sunday on or after a date, the month of a date, or the rolling window ending on it.", "items": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, "default": [] }, "videoDetails": { "title": "Comments and keywords (US videos)", "type": "boolean", "description": "One more call per video: up to 200 top comments with likes, the comment keywords TikTok extracts, the creator's store region. TikTok serves this record logged out for US videos only; other countries' rows say `detail_status: login_required` and are not charged for it.", "default": false }, "topAdsCountries": { "title": "Top Ads countries", "type": "array", "description": "Used when `sections` has Top Ads. An ad seen in several countries' lists comes once.", "items": { "type": "string", "enum": [ "AR", "AU", "BR", "CA", "CO", "FR", "DE", "ID", "IT", "JP", "MY", "MX", "NL", "PK", "PH", "RO", "SA", "SG", "ZA", "KR", "ES", "SE", "TH", "TR", "AE", "GB", "US", "VN" ], "enumTitles": [ "Argentina", "Australia", "Brazil", "Canada", "Colombia", "France", "Germany", "Indonesia", "Italy", "Japan", "Malaysia", "Mexico", "Netherlands", "Pakistan", "Philippines", "Romania", "Saudi Arabia", "Singapore", "South Africa", "South Korea", "Spain", "Sweden", "Thailand", "Turkey", "United Arab Emirates", "United Kingdom", "United States", "Vietnam" ] }, "default": [ "US" ] }, "topAdsPeriod": { "title": "Top Ads period", "enum": [ "7", "30", "180" ], "type": "string", "description": "The Top Ads period.", "default": "30" }, "topAdsSortBy": { "title": "Top Ads sort", "enum": [ "for_you", "ctr", "like", "impression", "play_2s_rate", "play_6s_rate", "cvr" ], "type": "string", "description": "TikTok's own order of the list. `for_you` changes between sessions; `ctr` is stable. `rank` on each row is the position in this order.", "default": "ctr" }, "topAdsIndustries": { "title": "Top Ads industries", "type": "array", "description": "Creative Center industries by name (`Apparel & Accessories`, `Games`) or id.", "items": { "type": "string", "pattern": "\\S" }, "default": [] }, "topAdsObjectives": { "title": "Top Ads objectives", "type": "array", "description": "Campaign objectives. `Product sales` (and `Conversions`) give the commerce ads rivals sell as \"trending products\".", "items": { "type": "string", "enum": [ "Traffic", "App Installs", "Conversions", "Video Views", "Reach", "Lead Generation", "Product sales" ] }, "default": [] }, "topAdsLanguages": { "title": "Top Ads languages", "type": "array", "description": "Ad languages (ISO 639-1).", "items": { "type": "string", "enum": [ "en", "es", "ar", "vi", "th", "de", "id", "pt", "fr", "ms", "nl", "ja", "it", "ro", "zh-Hant", "ko" ] }, "default": [] }, "topAdsFormat": { "title": "Top Ads format", "enum": [ "all", "video", "image" ], "type": "string", "description": "The ad format filter.", "default": "all" }, "topAdsLikes": { "title": "Top Ads likes", "enum": [ "all", "top_20", "top_40", "top_60", "top_80", "top_100" ], "type": "string", "description": "TikTok's likes tier filter.", "default": "all" }, "topAdsKeyword": { "title": "Top Ads keyword", "maxLength": 100, "type": "string", "description": "Keep ads whose caption or brand contains these words. The Creative Center serves no keyword search logged out, so the lists are swept and matched (this switches `topAdsSweep` on)." }, "topAdsSweep": { "title": "Go past 20 ads per list", "type": "boolean", "description": "Logged out a Top Ads list holds 20 ads. The sweep reads the same country and period under every sort, objective, likes tier, industry and language and keeps the new ads.", "default": false }, "topAdsDetails": { "title": "Top Ads details", "type": "boolean", "description": "One more call per ad: landing page, countries, comments, shares, objectives, keyword list.", "default": true }, "topAdsMetrics": { "title": "Top Ads curves and percentiles", "type": "boolean", "description": "Ten more calls per ad: the per-second CTR, CVR, clicks, conversions and retention curves and the five percentiles TikTok shows on the ad page.", "default": false }, "topAdsSpotlight": { "title": "Top Ads Spotlight", "type": "boolean", "description": "The hand-picked Spotlight ads with TikTok's expert note.", "default": false }, "startUrls": { "title": "Start URLs", "type": "array", "description": "Creative Center URLs copied from the browser: a trends hashtag list (its country, period and industry are kept), a hashtag's page, the top videos page, a Top Ads list or ad page, the Spotlight page. A text file, CSV or published Google Sheet with one URL per line works too.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "adIds": { "title": "Top Ads ids", "type": "array", "description": "Creative Center Top Ads ids (or their page URLs) to fetch with their detail record. An id TikTok no longer has comes back as a free `not_found` row.", "items": { "type": "string", "pattern": "^(\\d{15,21}|https?://ads\\.tiktok\\.com/\\S+/topads/\\d{15,21}\\S*)$" }, "default": [] }, "maxItems": { "title": "Max rows", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "The most charged rows (hashtags, videos, Top Ads together) this run delivers. 0 = no limit. Free rows (labels, summaries) do not count.", "default": 0 }, "trackChanges": { "title": "Track rank changes", "type": "boolean", "description": "Remember this task's lists between runs: every row gets `previous_rank`, `rank_change`, `rank_velocity_per_day`, `is_new`, `first_seen_at` and `times_seen`.", "default": false }, "onlyNew": { "title": "Only new entries", "type": "boolean", "description": "Deliver and charge only hashtags, videos and Top Ads this task has not delivered before (a Top Ad whose likes or CTR changed comes back as `changed`). Turns the memory on.", "default": false }, "includeEnded": { "title": "Say what left the lists", "type": "boolean", "description": "A free `ended` row for each entry an earlier run delivered that a complete read of the same list no longer returns. Turns the memory on.", "default": false }, "stateStoreName": { "title": "Memory name", "pattern": "^[A-Za-z0-9._-]{1,100}$", "type": "string", "description": "Name of the memory between runs. Empty = derived from the lists (not the dates), so the same task always meets its own memory." }, "summaryRows": { "title": "Summary rows", "type": "boolean", "description": "Free rows after the data: each hashtag used in the run's video titles and ad captions (and whether it is also trending), each Top Ads brand, each landing page.", "default": false }, "outputFormat": { "title": "Output format", "enum": [ "full", "compact" ], "type": "string", "description": "`compact` is for sheets and AI agents; billing is the same. With downloadMedia it keeps the stored files' links (`image_file_url`, `video_file_url`, `media_files`).", "default": "full" }, "downloadMedia": { "title": "Store media files", "enum": [ "none", "images", "all" ], "type": "string", "description": "TikTok's media links expire (`media_expires_at`). Store the files in the run's key-value store and get links that do not; a file two rows share is stored and billed once per run.", "default": "none" }, "transcribeVideos": { "title": "Transcribe videos (AI)", "type": "boolean", "description": "The spoken words of each top video and Top Ad, with the language and the first three seconds (`hook_3s`). A video without speech is not charged.", "default": false }, "transcriptTiming": { "title": "Time the transcripts (AI)", "type": "boolean", "description": "With transcribeVideos: word timestamps from a second model call, so `hook_3s` is the words of the first three seconds of speech and `speech_seconds` and `transcript_segments` are filled. Without it the transcript is the spoken words and `hook_3s` its first eight words.", "default": false }, "tagAds": { "title": "Tag each Top Ad (AI)", "type": "boolean", "description": "Typed tags from the caption: angle, CTA intent, tone, offer type, funnel stage and sentiment, each with its confidence (`analysis_*`). The same tags as our other ad library actors.", "default": false }, "analyzeAds": { "title": "Analyse each Top Ad (AI)", "type": "boolean", "description": "A short written read of each Top Ad: hook, offer, audience, strategy.", "default": false }, "trendDigest": { "title": "Trend digest (AI)", "type": "boolean", "description": "One `digest` row at the end: what is trending in the lists this run read, the themes, the rising hashtags and what to act on, written from the rows' own numbers.", "default": false }, "openaiApiKey": { "title": "OpenAI API key (optional)", "type": "string", "description": "Your own key for `transcribeVideos`, `analyzeAds` and `trendDigest`, if you want the model usage on your account. Not needed: the Actor has its own." }, "runTag": { "title": "Run tag", "maxLength": 200, "type": "string", "description": "Your own label, copied onto every row (`run_tag`)." }, "resumeFromRunId": { "title": "Continue an earlier run", "pattern": "^[A-Za-z0-9]{17}$", "type": "string", "description": "The id of a run of this Actor with the same input that stopped early (timeout, abort): this run continues where it stopped, without delivering or billing its rows again." } } }, "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 } } } } } } } } } }