tiktok-search-videos

What this skill does

# TikTok — Search Videos

> search keyword → 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 TikTok video search results for a given keyword using the `/api/search/item/full/` endpoint triggered by navigating to the search results page.

## Prerequisites

- Browser is open and can access `https://www.tiktok.com`
- **Login required**: TikTok blocks video search API for non-logged-in users; ensure the browser has an active TikTok session

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

### Network Capture: Search video results (parameters injected via URL navigation)

`/api/search/item/full/` requires TikTok's dynamic signing; navigate to the search page to trigger it automatically:

1. `navigate https://www.tiktok.com/search/video?q={keyword}`
2. `wait stable`
3. `network requests --type xhr,fetch --filter "search/item/full"`
4. `network request <id>`

Endpoint characteristic: URL contains `/api/search/item/full/` with `keyword={keyword}&cursor=0`

Error handling: If no matching request appears after navigation, take a `screenshot` to verify the page loaded correctly (check for anti-bot challenge), then retry once.

Output example:
```json
{
  "status_code": 0,
  "cursor": "12",    // use to identify next-page requests
  "has_more": 1,     // 0 when all results exhausted
  "item_list": [
    {
      "id": "7212410220977392938",
      "desc": "Daily Push Up Workout🚀#fitness #athlete",
      "createTime": 1679270124,
      "isAd": false,
      "locationCreated": "US",
      "author": {
        "uniqueId": "marcusriosofficial",
        "nickname": "Marcus Rios",
        "verified": false,
        "signature": "Former NFL Athlete 🏈",
        "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": []
    }
  ]
}
```

To build the `webVideoUrl` for each item: `https://www.tiktok.com/@{item.author.uniqueId}/video/{item.id}`

### Network Capture: Search results pagination (page 2+)

After reading page 1, scroll down to load the next page:

1. `scroll down`
2. `wait stable`
3. `network requests --type xhr,fetch --filter "search/item/full"`
4. Find the request where the URL `cursor` value is higher than the previous page (e.g., `cursor=12`, `cursor=24`)
5. `network request <id>`

Termination: `has_more` is `0` in response, or `item_list` is empty.

## Pagination

**DOM Pagination**: Scroll triggers new `search/item/full` requests. Each page returns 12 items. Cursor increments by 12 per page. Termination: `has_more === 0` or empty `item_list`.

## Success Criteria

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

## Known Limitations

- `search/item/full` requires dynamic signing — always use navigate + network capture
- **Login required**: TikTok blocks the video search API for non-logged-in users — `search/item/full` will not be triggered without an active TikTok session; exploration was done on a logged-in browser and this dependency was not caught at the time
- Search returns ~12 videos per page (fewer than hashtag's 30 per page)
- Logged-in users may see personalized results; use a fresh browser session for unbiased results
- `searchQuery` field is not returned in the raw API response body

## Execution Efficiency

- **Batch orchestration**: Loop multiple keywords serially in one session; add 2–3s between navigations.
- **Test before batch execution**: Test with 1 keyword first before running the full list.
- **Error resumption**: Save results keyword-by-keyword; resume from the failed keyword on error.

## Experience Notes

Path: `{working-directory}/browser-act-skill-forge-memories/tiktok-scraper-tiktok-search-videos.memory.md`

**Before execution**: If the file exists, read it first — it records unexpected situations from past executions; adjust strategy accordingly.

**After execution**: If an unexpected situation occurs (strategy failed, page redesigned, anti-scraping upgraded), append a line:
`{YYYY-MM-DD}: {what happened} → {conclusion}`

Normal execution does not write to the file.