TikTok — Hashtag Videos

hashtag name → challenge info + paginated video list with author, engagement, music, and video metadata

Language

Objective

Prerequisites

• Browser is open and can access https://www.tiktok.com
• No login required for public hashtag data
• Browser must use a non-HK proxy (TikTok has shut down in Hong Kong)

Pre-execution Checks

1. Tool Readiness

Capability Components

This Skill's operational boundary = what the user can manually do in their browser. It only reads data already displayed to the user on the page, never bypassing authentication or access controls. JS code is encapsulated in Python files under the scripts/ directory, invoked via eval "$(python scripts/xxx.py {params})". $(...) is bash syntax; it is recommended to use the bash tool for execution.

API: Get challenge ID from hashtag name

• {hashtag}: hashtag name without #, e.g., fitness

{
  "id": "9261",             // challengeID — required for item_list requests
  "title": "fitness",       // canonical hashtag title
  "videoCount": "63107035", // total videos under this hashtag
  "viewCount": "760591731095" // total views
}

Network Capture: Hashtag video list (parameters injected via URL navigation)

1. navigate https://www.tiktok.com/tag/{hashtag}
2. wait stable
3. network requests --type xhr,fetch --filter "challenge/item_list"
4. network request <id>

{
  "cursor": "30",   // use as cursor value to identify next page's request
  "hasMore": true,  // false when all pages exhausted
  "itemList": [
    {
      "id": "7212410220977392938",
      "desc": "Daily Push Up Workout🚀#fitness #athlete",
      "createTime": 1679270124,
      "isAd": false,
      "isPinned": false,
      "locationCreated": "US",
      "author": {
        "uniqueId": "marcusriosofficial",  // username for webVideoUrl
        "nickname": "Marcus Rios",
        "verified": false,
        "signature": "Former NFL Athlete 🏈",
        "bioLink": null,
        "avatarThumb": "https://...",
        "privateAccount": false
      },
      "authorStats": {
        "followerCount": 423500,
        "followingCount": 50,
        "heart": 10000000,
        "videoCount": 1277,
        "diggCount": 869
      },
      "stats": {
        "diggCount": 367500,
        "shareCount": 6041,
        "playCount": 4500000,
        "commentCount": 942,
        "collectCount": 56691
      },
      "video": {
        "duration": 48,
        "height": 1280,
        "width": 720,
        "cover": "https://...",
        "definition": "720p",
        "format": "mp4"
      },
      "music": {
        "id": "7176546707423889410",
        "title": "Trap Money so Big (Remix)",
        "authorName": "Iqbal12",
        "original": false,
        "coverMedium": "https://..."
      },
      "textExtra": [{"hashtagId": "9261", "hashtagName": "fitness"}],
      "effectStickers": [],
      "imagePost": null  // non-null for slideshow posts
    }
  ]
}

Network Capture: Hashtag video list pagination (page 2+)

1. scroll down
2. wait stable
3. network requests --type xhr,fetch --filter "challenge/item_list"
4. Find the request whose URL contains a cursor value higher than the previous page (e.g., cursor=30, cursor=60)
5. network request <id>

Composite: Full hashtag extraction (challenge ID + paginated video list)

1. eval "$(python scripts/get-challenge-id.py '{hashtag}')" → record id as challengeId (confirms hashtag exists)
2. navigate https://www.tiktok.com/tag/{hashtag} → wait stable
3. network requests --filter "challenge/item_list" → network request <id> → collect itemList, note cursor and hasMore
4. While hasMore is true: a. scroll down → wait stable b. network requests --filter "challenge/item_list" → find new request (cursor changed) → network request <id> c. Collect itemList, update hasMore
5. Merge all collected itemList arrays

Pagination

Success Criteria

Known Limitations

• Requires non-HK proxy (TikTok shut down in Hong Kong)
• challenge/item_list requires dynamic signing — always use navigate + network capture
• get-challenge-id.py (challenge/detail) works via direct fetch without signing
• Private or age-restricted hashtags may return empty itemList
• Page returns ~30 videos per scroll; high-volume extraction requires many scroll iterations

Execution Efficiency

• Batch orchestration: Loop through multiple hashtags serially in one session; do not parallelize within one browser. Add 2–3s intervals between navigations.
• Test before batch execution: Test with 1 hashtag first, then run the full batch.
• Error resumption: Save results page-by-page; resume from the last successful page on failure.

Experience Notes