mirror of
https://github.com/MODSetter/SurfSense.git
synced 2026-07-16 23:01:06 +02:00
6b15d610d9
Brings the three newer verbs to parity with tiktok.scrape everywhere it was wired: MCP tools (+ selfcheck manifest), the chat subagent prompt/description, the playground catalog, the native docs page, and the SEO marketing page. Also adds live e2e stages for comments, user search, and trending. Docs/FAQ now state the real contract: profile metadata is reliable while its video list can be withheld, and keyword video search is walled (use user search for accounts).
97 lines
4.3 KiB
Text
97 lines
4.3 KiB
Text
---
|
|
title: TikTok
|
|
description: Scrape public TikTok videos, comments, accounts, and trending feeds
|
|
---
|
|
|
|
The TikTok connector pulls structured public data from TikTok across four verbs: **scrape** (videos), **comments**, **user search** (accounts), and **trending**. Every verb returns `{ "items": [...] }` and is billed per returned item; surfaced errors (an `errorCode` field, e.g. a withheld feed) are never charged.
|
|
|
|
## Scrape videos
|
|
|
|
```bash
|
|
POST /api/v1/workspaces/{workspace_id}/scrapers/tiktok/scrape
|
|
```
|
|
|
|
Give it URLs (a video, a profile, a hashtag, or a search page) and/or profiles, hashtags, or search terms; returns videos (caption, author, play/like/comment/share counts, music, hashtags, timestamps, and the web URL). At least one of `urls`, `profiles`, `hashtags`, or `search_queries` is required.
|
|
|
|
| Field | Default | Description |
|
|
|-------|---------|-------------|
|
|
| `urls` | — | TikTok URLs: a video, a profile (`/@<user>`), a hashtag (`/tag/<name>`), or a search URL (max 20 sources per call) |
|
|
| `profiles` | — | Profile usernames, with or without a leading `@` |
|
|
| `hashtags` | — | Hashtag names, without the `#` |
|
|
| `search_queries` | — | Search terms to run on TikTok |
|
|
| `results_per_page` | `10` | Max videos per profile/hashtag/search target |
|
|
| `max_items` | `10` | Max total videos returned across all sources (hard cap 100) |
|
|
|
|
```bash
|
|
curl -X POST "$BASE_URL/api/v1/workspaces/1/scrapers/tiktok/scrape" \
|
|
-H "Authorization: Bearer $SURFSENSE_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{ "hashtags": ["food"], "max_items": 25 }'
|
|
```
|
|
|
|
<Callout type="info">
|
|
Video and hashtag targets are the reliable video paths. A `profiles` target returns the account's **metadata** (name, followers, bio, verification) reliably, but TikTok often withholds its **video list** from automated clients — so a profile can return metadata with no videos. Keyword **video** search is login-walled and returns a surfaced error; to find accounts by keyword use **user search** below.
|
|
</Callout>
|
|
|
|
## Comments
|
|
|
|
```bash
|
|
POST /api/v1/workspaces/{workspace_id}/scrapers/tiktok/comments
|
|
```
|
|
|
|
Given TikTok video URLs, returns each video's public comment thread: comment text, author, like count, and reply count (replies carry `repliesToId`, the parent comment id).
|
|
|
|
| Field | Default | Description |
|
|
|-------|---------|-------------|
|
|
| `video_urls` | — | TikTok video URLs (`/@<user>/video/<id>`), max 20 per call |
|
|
| `comments_per_video` | `20` | Max comments per video |
|
|
| `max_items` | `20` | Max total comments returned (hard cap 100) |
|
|
|
|
```bash
|
|
curl -X POST "$BASE_URL/api/v1/workspaces/1/scrapers/tiktok/comments" \
|
|
-H "Authorization: Bearer $SURFSENSE_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{ "video_urls": ["https://www.tiktok.com/@nasa/video/123"], "max_items": 50 }'
|
|
```
|
|
|
|
## User search
|
|
|
|
```bash
|
|
POST /api/v1/workspaces/{workspace_id}/scrapers/tiktok/user_search
|
|
```
|
|
|
|
Finds public TikTok accounts by keyword — the reliable account-discovery path. Returns matching profiles with name, followers, bio, and verification.
|
|
|
|
| Field | Default | Description |
|
|
|-------|---------|-------------|
|
|
| `queries` | — | Keywords to find accounts by, e.g. `["nasa", "cooking"]` (max 20) |
|
|
| `results_per_query` | `10` | Max accounts per query |
|
|
| `max_items` | `10` | Max total accounts returned (hard cap 100) |
|
|
|
|
```bash
|
|
curl -X POST "$BASE_URL/api/v1/workspaces/1/scrapers/tiktok/user_search" \
|
|
-H "Authorization: Bearer $SURFSENSE_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{ "queries": ["space agency"], "max_items": 20 }'
|
|
```
|
|
|
|
## Trending
|
|
|
|
```bash
|
|
POST /api/v1/workspaces/{workspace_id}/scrapers/tiktok/trending
|
|
```
|
|
|
|
Returns the current trending videos from TikTok's Explore feed — no input needed beyond how many to return. Items use the same video shape as **scrape** and bill on the same per-video meter.
|
|
|
|
| Field | Default | Description |
|
|
|-------|---------|-------------|
|
|
| `max_items` | `20` | Max trending videos returned (hard cap 100) |
|
|
|
|
```bash
|
|
curl -X POST "$BASE_URL/api/v1/workspaces/1/scrapers/tiktok/trending" \
|
|
-H "Authorization: Bearer $SURFSENSE_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{ "max_items": 30 }'
|
|
```
|
|
|
|
For the full input and output JSON schemas and generated code snippets in your language, open **API Playground → TikTok** in your workspace.
|