mirror of
https://github.com/MODSetter/SurfSense.git
synced 2026-07-18 23:11:12 +02:00
96 lines
4.2 KiB
Text
96 lines
4.2 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 or hashtags; returns videos (caption, author, play/like/comment/share counts, music, hashtags, timestamps, and the web URL). At least one of `urls`, `profiles`, or `hashtags` 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 `#` |
|
|
| `results_per_page` | `10` | Max videos per profile/hashtag 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. There is no keyword **video** search (TikTok's own search is login-walled); 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.
|