TikTok Hashtag Video Feed & Stats Extractor

{
  "description": "Collect all-time stats for one or more TikTok hashtags and/or the videos underneath them. Stats mode is the cheapest; feed mode returns the public US hashtag feed; search mode returns one page of keyword search; auto combines stats and feed and adds search when the feed is short.",
  "properties": {
    "hashtags": {
      "description": "Hashtags to collect. Accepts a bare tag, #tag, or a TikTok tag URL. Case-insensitive, duplicates removed. Up to 10.",
      "editor": "stringList",
      "items": {
        "type": "string"
      },
      "maxItems": 10,
      "minItems": 1,
      "prefill": [
        "fitness"
      ],
      "title": "Hashtags",
      "type": "array"
    },
    "includeStatsRow": {
      "default": true,
      "description": "Emit the aggregate hashtag stats row before video rows in feed, search and auto modes. Stats mode always emits it.",
      "title": "Include Stats Row",
      "type": "boolean"
    },
    "maxHashtags": {
      "default": 10,
      "description": "Process no more than this many hashtags from the list (1–10). Extra hashtags are skipped.",
      "maximum": 10,
      "minimum": 1,
      "title": "Max Hashtags",
      "type": "integer"
    },
    "maxVideosPerHashtag": {
      "default": 30,
      "description": "Upper bound on videos per hashtag for feed, search and auto modes (0–300). Use 0 for stats only. TikTok usually returns fewer than requested: the feed is served in pages of about 30 and many tags stop after roughly 100–150 rows.",
      "maximum": 300,
      "minimum": 0,
      "prefill": 0,
      "title": "Max Videos Per Hashtag",
      "type": "integer"
    },
    "mode": {
      "default": "stats",
      "description": "What to collect. 'stats' returns one aggregate row per hashtag (cheapest). 'feed' returns the public hashtag video feed. 'search' returns one page of TikTok keyword/hashtag search results. 'auto' returns stats plus the feed and adds search results only when the feed is shorter than one page.",
      "editor": "select",
      "enum": [
        "stats",
        "feed",
        "search",
        "auto"
      ],
      "enumTitles": [
        "Stats only — video and view totals",
        "Hashtag feed — videos under the tag",
        "Search — one page of TikTok results",
        "Auto — stats + feed, search when short"
      ],
      "prefill": "stats",
      "title": "Mode",
      "type": "string"
    },
    "proxyConfiguration": {
      "description": "Optional. Leave empty to use the built-in US residential connection with automatic fallback. Set your own Apify proxy configuration here to override it. Feed mode uses the most residential bandwidth, which is billed by Apify proxy usage.",
      "editor": "proxy",
      "title": "Proxy Configuration",
      "type": "object"
    },
    "region": {
      "default": "US",
      "description": "Market used for the hashtag feed. Only the United States is verified to return a public feed; other markets are not exposed yet.",
      "editor": "select",
      "enum": [
        "US"
      ],
      "enumTitles": [
        "United States (verified)"
      ],
      "title": "Region",
      "type": "string"
    }
  },
  "required": [
    "hashtags"
  ],
  "schemaVersion": 1,
  "title": "TikTok Hashtag Stats and Video Feed Input",
  "type": "object"
}

{
  "actorOutputSchemaVersion": 1,
  "description": "Aggregate hashtag stats rows (video/view totals, source, region) and video rows (caption, author, music, engagement, provenance). Use the recordType field to distinguish rows.",
  "properties": {
    "data": {
      "description": "Dataset containing hashtag_metadata stats rows and/or post video rows. Stats rows carry all-time totals; post rows carry the video payload plus source, position, region, scrapedAt, and carriesSearchedHashtag.",
      "template": "{{links.apiDefaultDatasetUrl}}/items",
      "title": "Hashtag Data",
      "type": "string"
    }
  },
  "title": "TikTok Hashtag Stats and Video Feed Output"
}

{
  "actorSpecification": 1,
  "fields": {
    "announcementBody": {
      "description": "Optional challenge announcement body text",
      "title": "Announcement Body",
      "type": "string"
    },
    "announcementTitle": {
      "description": "Optional challenge announcement title",
      "title": "Announcement Title",
      "type": "string"
    },
    "author": {
      "description": "Author snapshot at time of scraping (id, username, displayName, followerCount, etc.)",
      "title": "Author",
      "type": "object"
    },
    "authorStats": {
      "description": "Follower, following, heart, video and digg counts for the author",
      "title": "Author Stats",
      "type": "object"
    },
    "caption": {
      "description": "Post caption/description text",
      "title": "Caption",
      "type": "string"
    },
    "carriesAnyHashtag": {
      "description": "True when the video's caption carries at least one hashtag entity",
      "title": "Carries Any Hashtag",
      "type": "boolean"
    },
    "carriesSearchedHashtag": {
      "description": "True when the video's own hashtag entities include the searched tag",
      "title": "Carries Searched Hashtag",
      "type": "boolean"
    },
    "collectCount": {
      "description": "Number of times post was saved/collected",
      "title": "Collect Count",
      "type": "integer"
    },
    "commentCount": {
      "description": "Number of comments",
      "title": "Comment Count",
      "type": "integer"
    },
    "coverLarger": {
      "description": "Large cover banner image URL",
      "title": "Cover Image (Large)",
      "type": "string"
    },
    "coverMedium": {
      "description": "Medium cover banner image URL",
      "title": "Cover Image (Medium)",
      "type": "string"
    },
    "coverThumb": {
      "description": "Thumbnail cover image URL",
      "title": "Cover Image (Thumb)",
      "type": "string"
    },
    "createTime": {
      "description": "Unix timestamp when the post was created",
      "title": "Create Time",
      "type": "integer"
    },
    "createdAt": {
      "description": "ISO 8601 timestamp of post creation (UTC)",
      "title": "Created At",
      "type": "string"
    },
    "desc": {
      "description": "Optional hashtag description",
      "title": "Description",
      "type": "string"
    },
    "duetEnabled": {
      "description": "Whether duets are allowed on this post",
      "title": "Duet Enabled",
      "type": "boolean"
    },
    "hashtag": {
      "description": "The requested hashtag (without #) on stats rows",
      "title": "Hashtag",
      "type": "string"
    },
    "hashtagId": {
      "description": "TikTok internal challenge ID (string)",
      "title": "Hashtag ID",
      "type": "string"
    },
    "hashtagName": {
      "description": "Canonical hashtag name as TikTok stores it",
      "title": "Hashtag Name",
      "type": "string"
    },
    "hashtags": {
      "description": "Hashtags used in the post, each with id and name",
      "title": "Hashtags",
      "type": "array"
    },
    "images": {
      "description": "Slideshow images for photo posts (postType='slideshow'). Each item has ordinal, width, height, urlList.",
      "title": "Images",
      "type": "array"
    },
    "isAd": {
      "description": "Whether the post is a paid advertisement",
      "title": "Is Ad",
      "type": "boolean"
    },
    "isCommerce": {
      "description": "Whether this is a commercial/brand hashtag",
      "title": "Is Commerce",
      "type": "boolean"
    },
    "likeCount": {
      "description": "Number of likes",
      "title": "Like Count",
      "type": "integer"
    },
    "locationCreated": {
      "description": "Country code where the post was created",
      "title": "Location Created",
      "type": "string"
    },
    "mediaUrlExpiresAt": {
      "description": "ISO 8601 UTC timestamp when signed media URLs expire",
      "title": "Media URL Expires At",
      "type": "string"
    },
    "mentions": {
      "description": "@mentions in the caption with username and offsets",
      "title": "Mentions",
      "type": "array"
    },
    "music": {
      "description": "Music/sound used in the post (id, title, authorName, duration, playUrl, coverUrl)",
      "title": "Music",
      "type": "object"
    },
    "playCount": {
      "description": "Number of video plays",
      "title": "Play Count",
      "type": "integer"
    },
    "position": {
      "description": "1-based position in the collected feed/search list for the hashtag",
      "title": "Position",
      "type": "integer"
    },
    "postId": {
      "description": "Unique TikTok post/video ID (string)",
      "title": "Post ID",
      "type": "string"
    },
    "postType": {
      "description": "Either 'video' or 'slideshow'",
      "title": "Post Type",
      "type": "string"
    },
    "postUrl": {
      "description": "Direct URL to the TikTok post",
      "title": "Post URL",
      "type": "string"
    },
    "profileLarger": {
      "description": "Large profile/cover image URL for the hashtag",
      "title": "Profile Image (Large)",
      "type": "string"
    },
    "profileMedium": {
      "description": "Medium profile image URL for the hashtag",
      "title": "Profile Image (Medium)",
      "type": "string"
    },
    "profileThumb": {
      "description": "Thumbnail profile image URL for the hashtag",
      "title": "Profile Image (Thumb)",
      "type": "string"
    },
    "recordType": {
      "description": "Discriminator: 'hashtag_metadata' for aggregate stats rows, 'post' for video rows",
      "title": "Record Type",
      "type": "string"
    },
    "region": {
      "description": "Market used for the run (US is the verified feed market)",
      "title": "Region",
      "type": "string"
    },
    "repostCount": {
      "description": "Number of reposts (from statsV2)",
      "title": "Repost Count",
      "type": "integer"
    },
    "scrapedAt": {
      "description": "UTC ISO 8601 timestamp when the record was built",
      "title": "Scraped At",
      "type": "string"
    },
    "searchedHashtag": {
      "description": "The normalized hashtag input that produced this record (without #)",
      "title": "Searched Hashtag",
      "type": "string"
    },
    "shareCount": {
      "description": "Number of shares",
      "title": "Share Count",
      "type": "integer"
    },
    "shareEnabled": {
      "description": "Whether sharing is enabled on this post",
      "title": "Share Enabled",
      "type": "boolean"
    },
    "shareMeta": {
      "description": "Share metadata object with title and desc fields",
      "title": "Share Meta",
      "type": "object"
    },
    "source": {
      "description": "'challenge_detail' on stats rows; 'feed' or 'search' on video rows",
      "title": "Source",
      "type": "string"
    },
    "stitchEnabled": {
      "description": "Whether stitching is allowed on this post",
      "title": "Stitch Enabled",
      "type": "boolean"
    },
    "textExtra": {
      "description": "Raw TikTok caption entities (hashtags and mentions) when present",
      "title": "Text Extra",
      "type": "array"
    },
    "textLanguage": {
      "description": "Language code of the caption text",
      "title": "Text Language",
      "type": "string"
    },
    "video": {
      "description": "Video metadata (width, height, duration, ratio, playUrl, cover)",
      "title": "Video",
      "type": "object"
    },
    "videoCount": {
      "description": "All-time number of videos using this hashtag, from statsV2 (string to avoid overflow)",
      "title": "Video Count",
      "type": "string"
    },
    "viewCount": {
      "description": "All-time views across all videos using this hashtag, from statsV2 (string)",
      "title": "View Count",
      "type": "string"
    }
  },
  "title": "TikTok Hashtag Stats and Video Feed Dataset",
  "views": {
    "overview": {
      "display": {
        "component": "table",
        "properties": {
          "caption": {
            "format": "text",
            "label": "Caption"
          },
          "carriesSearchedHashtag": {
            "format": "text",
            "label": "Has Tag"
          },
          "commentCount": {
            "format": "number",
            "label": "Comments"
          },
          "hashtagName": {
            "format": "text",
            "label": "Hashtag Name"
          },
          "likeCount": {
            "format": "number",
            "label": "Likes"
          },
          "playCount": {
            "format": "number",
            "label": "Plays"
          },
          "position": {
            "format": "number",
            "label": "Position"
          },
          "postId": {
            "format": "text",
            "label": "Post ID"
          },
          "postUrl": {
            "format": "link",
            "label": "Post URL"
          },
          "recordType": {
            "format": "text",
            "label": "Type"
          },
          "region": {
            "format": "text",
            "label": "Region"
          },
          "scrapedAt": {
            "format": "text",
            "label": "Scraped At"
          },
          "searchedHashtag": {
            "format": "text",
            "label": "Hashtag"
          },
          "source": {
            "format": "text",
            "label": "Source"
          },
          "videoCount": {
            "format": "text",
            "label": "Video Count"
          },
          "viewCount": {
            "format": "text",
            "label": "View Count"
          }
        }
      },
      "title": "Overview",
      "transformation": {
        "fields": [
          "recordType",
          "searchedHashtag",
          "hashtagName",
          "videoCount",
          "viewCount",
          "source",
          "postId",
          "caption",
          "carriesSearchedHashtag",
          "position",
          "region",
          "scrapedAt",
          "playCount",
          "likeCount",
          "commentCount",
          "postUrl"
        ]
      }
    }
  }
}