# TikTok Shop API (ScrapeIO)

5 endpoints for public TikTok Shop 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/product

Product Details Price: 1 credit. MCP tool: `tiktok_product`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | The URL of the product to get details for. |
| `region` | string | no | Region for the product details request. |

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

### GET /v1/tiktok/shop/product/reviews

Product Reviews Price: 1 credit. MCP tool: `tiktok_shop_product_reviews`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | no | The URL of the product (required if productid is not provided) |
| `product_id` | string | no | The ID of the product (required if url is not provided) |
| `region` | string | no | The region of the product. |
| `page` | string | no | The page number of the reviews |

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

### GET /v1/tiktok/shop/products

Shop Products Price: 1 credit. MCP tool: `tiktok_shop_products`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | The TikTok Shop store URL. |
| `sort_by` | string (top, new_releases) | no | Sort products by best-selling items (top) or newest products (newreleases). |
| `region` | string (US, GB, DE, FR, IT, ID, MY, MX, PH, SG, ES, TH, VN, BR, JP, IE) | no | Region to get shop products from. |
| `cursor` | string | no | Cursor parameter from the previous response to retrieve the next page of products. |

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

### GET /v1/tiktok/shop/search

Shop Search Price: 1 credit. MCP tool: `tiktok_shop_search`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | Term you want to search for |
| `region` | string (US, GB, DE, FR, IT, ID, MY, MX, PH, SG, ES, TH, VN, BR, JP, IE) | no | Region to search shop products in. |
| `page` | string | no | Page number to retrieve |

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

### GET /v1/tiktok/user/showcase

User Showcase Price: 1 credit. MCP tool: `tiktok_user_showcase`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `handle` | string | yes | The handle of the user |
| `region` | string | no | Region to put the proxy in. |
| `cursor` | string | no | The cursor to the next page of products |

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