🤖 Let AI Collect TikTok Data for You

If the "one sentence" approach above doesn't work for your AI, you can copy the full skill text and paste it directly.

---
name: tiktok-scraper
description: 🎁 Permanently free — 10M entries on signup, 1 concurrent window. Zero-install skill: open a browser URL, the extension + logged-in session do the rest. TikTok video search, creator discovery, hashtag collection, creator profile, and user video export to CSV. Works with Claude Code, Codex, Cursor, Windsurf, ChatGPT (any AI client). No Python packages, no credentials, no headless setup.
---

# TikTok Scraper

> 🎁 Permanently free · 10 million entries on signup · 1 concurrent window for free users. Members unlock more parallel windows.

## What is this?

A skill that lets **any AI assistant** (Claude Code, Codex, Cursor, Windsurf, ChatGPT…) scrape TikTok data — video search, creator discovery, hashtag collection, creator profiles, or a specific creator's videos — and return it as a CSV. You don't install Python packages, configure headless browsers, or manage credentials. The AI orchestrates: it generates a task ID, opens a URL in the **user's own browser**, and downloads the result.

**Why a browser + extension?** The actual scrape runs inside the user's real TikTok session (logged in, with the MonsterGet browser extension installed). That's what keeps the accounts anti-ban safe.

**First-time setup (~2 minutes):** ① Register a free account at monsterget.com and install the extension (Chrome/Edge). ② Log into TikTok in the browser. Everything after that is repeatable and instant.

## Architecture

```
AI ──1. GET /api/agent/generate-task-id ──▶ {"taskId":"<uuid>"}
AI ──2. Open browser page  {pagePath}?auto=1&agentTaskId={taskId}&{param}=...&count=N
       Page (user browser, logged in + extension) ▶ POST /api/agent/scrape (creates task with our taskId)
       Extension executes scrape in TikTok tab
AI ──3. GET /api/agent/delivery/task/{taskId}/status  ▶ {status:"ready"}
AI ──4. GET /api/agent/delivery/task/{taskId}/data    ▶ CSV download
```

**Key invariant (v0.5):** the AI generates the taskId itself *before* opening the browser, so it never needs to read the browser address bar.

## Scrape types

> ⚠️ **This table may be stale.** New scrapers are NOT auto-synced into this skill file. Before mapping the user's request, fetch the live list (zero-auth, read-only):
> ```bash
> curl -s https://monsterget.com/api/agent/scrapers
> ```

| Type | pagePath | Param | Default | Max | Description |
|------|----------|-------|---------|-----|-------------|
| Video search | /tiktok-search-video | query | 50 | 300 | Search videos by keyword |
| Creator search | /tiktok-search-user | query | 30 | 300 | Find creators/users |
| Hashtag search | /tiktok-tag | query | 30 | 300 | Videos under a hashtag |
| Creator videos | /tiktok-user-videos | username | 50 | 300 | All videos by a creator |
| Creator profile | /tiktok-profile | username | 1 | 1 | Profile stats (followers, bio) |

## ⚡ Automation rules

**Opening the browser is fire-and-forget. Do NOT wait for the user to confirm.**

1. **Open + poll in one shot.** Run the browser command and the poll loop together. Do not message the user between them.
2. **Never wait for user confirmation** after opening the browser.
3. **Polling already detects completion.** Exit the moment status is `ready`.
4. **Multiple scrapes run back-to-back, unattended.** Open → poll → download → next.
5. **A finished task frees the concurrency slot.** Only `pending`/`processing` tasks consume a slot.

## The full flow

### Step 0 — First-time setup (only needed once)

If the user hasn't used this before, guide them through:
1. Register and log in at https://monsterget.com
2. Install the browser extension from https://monsterget.com/install
3. Log into TikTok at https://www.tiktok.com

Run a test scrape to verify all three are working.

### Step 1 — Generate a taskId (zero-auth)

```bash
TASK_ID=$(curl -s https://monsterget.com/api/agent/generate-task-id | sed -n 's/.*"taskId":"\([^"]*\)".*/\1/p')
```

### Step 2 — Open the page in the user's browser (fire-and-forget)

Construct URL: `{pagePath}?auto=1&agentTaskId={TASK_ID}&{param}={value}&count=N`

⚠️ **Wrap URL in double quotes** — otherwise `&` is treated as a shell command separator.

Windows Edge: `start msedge "https://monsterget.com/tiktok-search-video?auto=1&agentTaskId=$TASK_ID&query=mike&count=10"`

### Step 3 — Poll until ready (every 5s, up to 60 times)

```bash
curl -s https://monsterget.com/api/agent/delivery/task/$TASK_ID/status
```

| status | meaning |
|--------|---------|
| processing | still running → keep polling |
| ready | data ready → download |
| downloaded | already fetched |

### Step 4 — Download CSV (one download, 24h expiry)

```bash
curl -OJ https://monsterget.com/api/agent/delivery/task/$TASK_ID/data
```

### Bulk creator profiles

For multiple creators at once:
```bash
start msedge "https://monsterget.com/tiktok-profile?auto=1&agentTaskId=$TASK_ID&usernames=mike,jenifer,tiktok&count=3"
```

The CSV contains one row per creator with aggregated profile stats.

### Running multiple scrapes (serial batch)

When the user asks for several scrapes at once, run them back-to-back without asking between tasks:

1. TASK_ID = generate-task-id
2. Open browser page 1 (fire-and-forget)
3. Poll until ready
4. Download CSV 1
5. TASK_ID = generate-task-id
6. Open browser page 2 ← do NOT wait for user
7. Poll → download
... repeat ...

## Error handling

| Symptom | Cause | Fix |
|---------|-------|-----|
| curl connection refused | platform not reachable | confirm monsterget.com is up |
| 404 delivery_not_found | wrong taskId, or a previous scrape still running (429 → page auto-retry timed out) | wait for the running task to reach ready/failed; only regenerate if you're sure nothing is running |
| processing > 5 min | extension/log in missing | confirm extension installed + logged in |
| 410 already_downloaded | already fetched once | run a new scrape |
| 429 too_many_concurrent | previous task still pending/processing | the page auto-retries — no action needed. **Slot frees when task completes** |
| 402 insufficient_credits | credits exhausted | signup grants 10M — almost never runs out |
| Page "extension not ready" | extension not installed | install extension, reload page |
| Page "please log in" | not logged into platform | log in, reload page |
| Can't open browser | AI in sandbox | user needs a local AI terminal |

## Gotchas

- **Use the extension-installed browser.** Never rely on the system default.
- **Never call POST /api/agent/scrape yourself.** The page does it automatically.
- **Keep the tab open** until ready. Closing it means no server copy is produced.

Chat AIs may not open your browser directly, but you can paste this link and it will guide you through: