tiktok-hashtag-videos

# TikTok — Hashtag Videos

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

## Language

All process output to user (progress updates, process notifications) follows the user's language.

## Objective

Extract the video list for a given TikTok hashtag using the `/api/challenge/item_list/` endpoint triggered by page navigation.

## 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

If browser-act has been confirmed available in the current session → skip this step.

Invoke `browser-act` via Skill tool to load usage. If installation or configuration issues arise, follow its guidance to resolve then retry.

## 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.

Below are all atomic capabilities discovered and verified during the exploration phase. Simply invoke them as needed — no need to read `scripts/*.py` source code or re-verify.

### API: Get challenge ID from hashtag name

`eval "$(python scripts/get-challenge-id.py '{hashtag}')"`

Parameters:
- `{hashtag}`: hashtag name without `#`, e.g., `fitness`

Output example:
```json
{
  "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)

`/api/challenge/item_list/` requires TikTok's dynamic signing (X-Bogus/X-Gnarly); direct fetch returns empty. Navigate to the hashtag page — TikTok's JS triggers the signed request automatically:

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>`

Endpoint characteristic: URL contains `/api/challenge/item_list/` with `cursor=0`

Error handling: If no matching request is found after navigation, take a `screenshot` to confirm the page loaded correctly, then retry navigation once. If the page shows a region-restriction notice, switch to a browser with a non-HK proxy.

Output example:
```json
{
  "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+)

After reading page 1, scroll down to trigger the next page request:

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>`

Termination: `hasMore` is `false` in response, or `itemList` is empty.

### 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

**DOM Pagination**: Scroll triggers new `challenge/item_list` requests. Each page returns 30 items. Cursor advances numerically (0 → 30 → 60...). Termination: `hasMore === false` or empty `itemList`.

## Success Criteria

`itemList.length >= 1` and first item has non-null `id`, `stats.playCount`, `author.uniqueId`

## 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 ma