# TikTok API (ScrapeIO)

23 endpoints for public TikTok data. Same response format and field names as every other platform.

## Basics

- Base URL: `https://scrapeio.com`
- Auth: send your key in the `x-api-key` header. Get a key at https://scrapeio.com/login (100 free credits, no card).
- Every endpoint is a GET with query parameters and returns JSON:
  `{ "success": true, "cached": false, "credits_used": 1, "credits_remaining": 99, "data": { ... } }`
- Field names are the same on every platform (`handle`, `followers`, `plays`, `likes`, `comments`, `created_at`).
- Lists return `data.items`, `data.cursor` and `data.has_more`. Pass `cursor` back to get the next page.
- Each endpoint has one listed price. Cached repeats, failed calls, private and not-found answers cost 0.
- Limit: 300 requests a minute per key.

## Errors

| Status | Meaning | Charged |
| --- | --- | --- |
| 200 | Success | Yes, unless cached |
| 400 | A parameter is missing or wrong | No |
| 401 | The key is missing or invalid | No |
| 402 | Not enough credits | No |
| 403 | The account or post is private | No |
| 404 | Not found on the platform | No |
| 429 | More than 300 requests a minute | No |
| 502 | Every source is down; retry shortly | No |

### GET /v1/tiktok/profile

TikTok profile: bio, avatar, followers, following, likes, video count. Price: 1 credit. MCP tool: `tiktok_profile`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `handle` | string | yes | TikTok username, with or without @. |

```bash
curl "https://scrapeio.com/v1/tiktok/profile?handle=nike" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v3/tiktok/profile/videos

A profile's videos, newest first, with plays, likes, comments, shares and saves. Price: 1 credit. MCP tool: `tiktok_profile_videos`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `handle` | string | yes | TikTok username, with or without @. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v3/tiktok/profile/videos?handle=nike" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v2/tiktok/video

One TikTok video by URL: stats, caption, author, music, download URL. Price: 5 credits. MCP tool: `tiktok_video`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | TikTok video URL. |

```bash
curl "https://scrapeio.com/v2/tiktok/video?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/tiktok/video/transcript

Spoken-word transcript of a TikTok video, from its captions. Price: 5 credits. MCP tool: `tiktok_transcript`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | TikTok video URL. |
| `language` | string | no | Preferred language code, e.g. en. |

```bash
curl "https://scrapeio.com/v1/tiktok/video/transcript?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/tiktok/video/comments

Comments on a TikTok video, most liked first. Price: 1 credit. MCP tool: `tiktok_comments`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | TikTok video URL. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/tiktok/video/comments?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/tiktok/video/comment/replies

Replies to one TikTok comment. Price: 1 credit. MCP tool: `tiktok_comment_replies`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | TikTok video URL. |
| `comment_id` | string | yes | Comment id from the comments endpoint. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/tiktok/video/comment/replies?url=...&comment_id=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/tiktok/search/keyword

Search TikTok videos by keyword. Price: 5 credits. MCP tool: `tiktok_search_keyword`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | Search text. |
| `sort_by` | string (relevance, most-liked, latest) | no | Sort order. |
| `date_posted` | string (all, yesterday, this-week, this-month, last-3-months, last-6-months) | no | Posted within. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/tiktok/search/keyword?query=coffee" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/tiktok/search/users

Search TikTok accounts by keyword. Price: 5 credits. MCP tool: `tiktok_search_users`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | Search text. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/tiktok/search/users?query=coffee" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/tiktok/search/hashtag

Videos under a hashtag, plus the hashtag's totals. Price: 5 credits. MCP tool: `tiktok_search_hashtag`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `hashtag` | string | yes | Hashtag, with or without #. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/tiktok/search/hashtag?hashtag=travel" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/tiktok/trending

Trending feed for a region. Price: 5 credits. MCP tool: `tiktok_trending`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `region` | string | no | Two-letter country code. |

```bash
curl "https://scrapeio.com/v1/tiktok/trending" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/tiktok/user/followers

A profile's followers, newest first. Price: 5 credits. MCP tool: `tiktok_followers`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `handle` | string | yes | TikTok username, with or without @. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/tiktok/user/followers?handle=nike" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/tiktok/user/liked

Videos a profile has liked (when public). Price: 1 credit. MCP tool: `tiktok_liked_videos`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `handle` | string | yes | TikTok username, with or without @. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/tiktok/user/liked?handle=nike" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/tiktok/song

A TikTok sound: title, author, duration, usage count. Price: 5 credits. MCP tool: `tiktok_song`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | TikTok sound or video URL. |

```bash
curl "https://scrapeio.com/v1/tiktok/song?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/tiktok/song/videos

Videos that use a sound. Price: 5 credits. MCP tool: `tiktok_song_videos`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `music_id` | string | yes | Sound id from the song endpoint. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/tiktok/song/videos?music_id=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/tiktok/user/following

Accounts a TikTok profile follows. Price: 5 credits. MCP tool: `tiktok_following`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `handle` | string | yes | TikTok username, with or without @. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/tiktok/user/following?handle=nike" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/tiktok/get-trending-feed

TikTok's trending feed for a country. Price: 5 credits. MCP tool: `tiktok_trending_feed`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `region` | string | no | Two-letter country code. |

```bash
curl "https://scrapeio.com/v1/tiktok/get-trending-feed" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/tiktok/collection/videos

Collection Videos Price: 5 credits. MCP tool: `tiktok_collection_videos`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | Public TikTok collection URL |
| `cursor` | string | no | Cursor to get more videos. |

```bash
curl "https://scrapeio.com/v1/tiktok/collection/videos?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/tiktok/live

Live Info Price: 5 credits. MCP tool: `tiktok_live`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `room_id` | string | yes | TikTok live room id. |
| `user_id` | string | yes | TikTok numeric user id for the live owner. |

```bash
curl "https://scrapeio.com/v1/tiktok/live?room_id=...&user_id=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/tiktok/profile/region

Profile Region Price: 5 credits. MCP tool: `tiktok_profile_region`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `handle` | string | yes | TikTok handle |

```bash
curl "https://scrapeio.com/v1/tiktok/profile/region?handle=nike" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/tiktok/search/suggestions

Search Suggestions Price: 5 credits. MCP tool: `tiktok_search_suggestions`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | Search query to get suggestions for |
| `region` | string | no | Region code for suggestions |

```bash
curl "https://scrapeio.com/v1/tiktok/search/suggestions?query=coffee" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/tiktok/search/top

Top Search Price: 5 credits. MCP tool: `tiktok_search_top`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | Keyword to search for |
| `publish_time` | string (yesterday, this-week, this-month, last-3-months, last-6-months, all-time) | no | Time Frame TikTok was posted |
| `sort_by` | string (relevance, most-liked, date-posted) | no | Sort by |
| `region` | string | no | Note, this doesn't filter the tiktoks only in a specfic region, it puts the proxy there. |
| `cursor` | string | no | Cursor to get more videos. |

```bash
curl "https://scrapeio.com/v1/tiktok/search/top?query=coffee" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/tiktok/user/audience

User's Audience Demographics Price: up to 130 credits. MCP tool: `tiktok_user_audience`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `handle` | string | yes | TikTok handle |

```bash
curl "https://scrapeio.com/v1/tiktok/user/audience?handle=nike" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/tiktok/user/live

Live Price: 5 credits. MCP tool: `tiktok_user_live`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `handle` | string | yes | TikTok handle |

```bash
curl "https://scrapeio.com/v1/tiktok/user/live?handle=nike" -H "x-api-key: $SCRAPEIO_API_KEY"
```