{ "openapi": "3.0.1", "info": { "title": "TikTok Hashtag Analytics", "description": "Analyze TikTok hashtags: total views, video volume, average and median engagement, top creators and videos, creator concentration, related hashtags, sounds, posting activity, and trend tracking. One report per hashtag.", "version": "1.0", "x-build-id": "ybwAr01GhDXLGNFwY" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/coregent~tiktok-hashtag-analytics/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-coregent-tiktok-hashtag-analytics", "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/coregent~tiktok-hashtag-analytics/runs": { "post": { "operationId": "runs-sync-coregent-tiktok-hashtag-analytics", "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/coregent~tiktok-hashtag-analytics/run-sync": { "post": { "operationId": "run-sync-coregent-tiktok-hashtag-analytics", "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": [ "hashtags" ], "properties": { "hashtags": { "title": "Hashtags", "maxItems": 100, "type": "array", "description": "One hashtag per line: booktok, #booktok or https://www.tiktok.com/tag/booktok all work. Case doesn't matter and duplicates are removed. You get one analytics report per hashtag. Up to 100 hashtags per run.", "items": { "type": "string" }, "default": [ "booktok" ] }, "mode": { "title": "Mode", "enum": [ "SNAPSHOT", "COMPARE", "TREND" ], "type": "string", "description": "SNAPSHOT: one current report per hashtag. COMPARE: same reports, plus each hashtag's rank within this run on total views, video count, median views, median engagement rate, creator diversity, content freshness, share rate and save rate. TREND: compares each report with earlier saved snapshots of the same hashtag (previous run, 7 and 30 days by default). Trend history starts with your first run.", "default": "SNAPSHOT" }, "videosPerHashtag": { "title": "Videos sampled per hashtag", "minimum": 20, "maximum": 1000, "type": "integer", "description": "How many of the hashtag's videos to analyze. TikTok serves the feed 20 videos per page, so multiples of 20 work best: 20, 40, 100, 200, 500 or 1000. Bigger samples give steadier medians and more related hashtags and sounds. Each report is billed per started 100 sampled videos. Small hashtags may return fewer; the report says how many were sampled.", "default": 40 }, "videosPublishedAfter": { "title": "Only videos published after", "type": "string", "description": "Optional. Only analyze sampled videos published on or after this date, e.g. 2026-10-01, \"7 days ago\" or \"30 days\". TikTok's hashtag feed is ranked, not chronological, so a strict date filter may return a smaller sample. Leave empty for no date limit.", "default": "" }, "region": { "title": "Region", "enum": [ "US", "GB", "FR", "JP", "VN", "SG" ], "type": "string", "description": "Region TikTok uses when serving the hashtag feed. TikTok's hashtag API supports these regions only.", "default": "US" }, "includeHashtagMetadata": { "title": "Global hashtag metadata", "type": "boolean", "description": "TikTok's own hashtag counters: total views, total video count, description and commerce flag, plus views per video. These are global, not computed from the sample.", "default": true }, "includeCreatorAnalytics": { "title": "Creator analytics", "type": "boolean", "description": "Unique creators, creator diversity, creator concentration, verified-creator share and the top creators in the sample.", "default": true }, "includeRelatedHashtags": { "title": "Related hashtags", "type": "boolean", "description": "Other hashtags used in the sampled captions, with how many sampled videos use each, their share of the sample, and their sample views.", "default": true }, "includeSoundAnalytics": { "title": "Sound analytics", "type": "boolean", "description": "Unique sounds, original-sound share, sound concentration and the top sounds in the sample.", "default": true }, "includeTopVideos": { "title": "Top videos", "type": "boolean", "description": "The most-viewed sampled videos with link, caption, date, engagement, creator, sound and hashtags.", "default": true }, "topVideosLimit": { "title": "Max top videos", "minimum": 0, "maximum": 50, "type": "integer", "description": "How many top videos to list per report.", "default": 10 }, "topCreatorsLimit": { "title": "Max top creators", "minimum": 0, "maximum": 50, "type": "integer", "description": "How many top creators to list per report.", "default": 10 }, "topCreatorsSortBy": { "title": "Rank top creators by", "enum": [ "sampleViews", "videosInSample", "sampleLikes", "followers" ], "type": "string", "description": "How top creators are ranked. 'Followers' only makes sense with creator profile enrichment on.", "default": "sampleViews" }, "relatedHashtagsLimit": { "title": "Max related hashtags", "minimum": 0, "maximum": 100, "type": "integer", "description": "How many related hashtags to list per report, most frequent first.", "default": 20 }, "topSoundsLimit": { "title": "Max top sounds", "minimum": 0, "maximum": 50, "type": "integer", "description": "How many top sounds to list per report.", "default": 10 }, "enrichCreatorProfiles": { "title": "Enrich top creators with follower counts", "type": "boolean", "description": "TikTok's hashtag feed doesn't include creator follower counts. Turn this on to look up the profiles of the top creators in each sample and add follower statistics (average / median / 90th-percentile followers) and the creator tier mix (nano to mega). Billed per creator profile fetched.", "default": false }, "maxCreatorsToEnrich": { "title": "Max creators to enrich per hashtag", "minimum": 1, "maximum": 100, "type": "integer", "description": "With enrichment on: how many creators per hashtag to look up, starting with the creators that have the most views in the sample.", "default": 10 }, "comparisonPeriods": { "title": "Comparison periods", "type": "array", "description": "Compare each report with a saved snapshot from: the previous run, or about 7, 30 or 90 days ago. Defaults to previous + 7 + 30 days in TREND mode. A period shows INSUFFICIENT_HISTORY until a snapshot that old exists.", "items": { "type": "string", "enum": [ "PREVIOUS", "7_DAYS", "30_DAYS", "90_DAYS" ], "enumTitles": [ "Previous run", "7 days ago", "30 days ago", "90 days ago" ] }, "default": [] }, "trackerKey": { "title": "Tracker key", "type": "string", "description": "Optional name for this tracking project, e.g. ai-hashtags. History is kept separately per tracker key, so the same hashtag can be tracked for several projects. Leave empty to use the default tracker.", "default": "" }, "saveHistory": { "title": "Save history snapshot", "type": "boolean", "description": "Save a compact snapshot of each report so later TREND runs can compare against it. Snapshots are only compared when the sample settings match, and runs less than 30 minutes apart don't create duplicates.", "default": true }, "includeSampleVideos": { "title": "Save the sampled videos", "type": "boolean", "description": "Also save every sampled video (normalized) to the run's key-value store as HASHTAG_SAMPLE_VIDEOS. The dataset stays one report per hashtag.", "default": false }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 15, "type": "integer", "description": "How many hashtags are analyzed in parallel. One hashtag's feed pages are always fetched in order.", "default": 5 } } }, "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 } } } } } } } } } }