# TikTok Posts

Scrape TikTok videos and photo posts by profile, hashtag, keyword, post URL, or sound — with full engagement metrics, author stats, hashtags, mentions, and music.

**Pricing:** $2 / 1k posts

**Endpoint:** `POST /api/v1/agents/tiktok/posts/run`

**Auth:** `Authorization: Bearer mk_live_...`

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `profiles` | array | No | TikTok usernames/handles to scrape posts from (with or without @). One per line. |
| `hashtags` | array | No | Hashtag names to scrape posts for (without #). One per line. |
| `searchQueries` | array | No | Free-text search queries to find matching posts. One per line. |
| `postURLs` | array | No | Direct TikTok video/post URLs to scrape. One per line. |
| `musics` | array | No | TikTok music/sound page URLs — returns posts that use each sound. One per line. |
| `resultsPerPage` | integer | No | Maximum posts to return per profile, hashtag, keyword, or sound. |

## Example

```bash
curl -X POST https://api.mindcase.co/api/v1/agents/tiktok/posts/run \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{}}'
```

```python
import requests

resp = requests.post(
    "https://api.mindcase.co/api/v1/agents/tiktok/posts/run",
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
    json={"params": {}},
)
data = resp.json()
```

## Get the results

`run` is async and returns a `job_id`. Poll until `status` is `completed`, then read the rows:

```bash
# 1) check status
curl https://api.mindcase.co/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"

# 2) when status == completed, fetch the rows
curl https://api.mindcase.co/api/v1/jobs/JOB_ID/results \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"
```

Full API reference (auth, jobs, balance, endpoints): https://mindcase.co/skills.md

## Response columns

| Field | Display name | Type |
|-------|--------------|------|
| `postUrl` | Post URL | url |
| `author` | Author | object |
| `caption` | Caption | text |
| `postedDate` | Posted Date | date |
| `views` | Views | number |
| `likes` | Likes | number |
| `comments` | Comments | number |
| `shares` | Shares | number |
| `saves` | Saves | number |
| `language` | Language | text |
| `isSlideshow` | Is Slideshow | boolean |
| `isAd` | Is Ad | boolean |
| `isSponsored` | Is Sponsored | boolean |
| `hashtags` | Hashtags | object_array |
| `mentions` | Mentions | object_array |
| `effects` | Effects | object_array |
| `slideshowImages` | Slideshow Images | object_array |
| `thumbnail` | Thumbnail | image |
| `durationS` | Duration (s) | number |
| `resolution` | Resolution | text |
| `sound` | Sound | object |
| `location` | Location | text |
| `locationAddress` | Location Address | text |
| `country` | Country | text |
| `hashtagViews` | Hashtag Views | number |
| `sourceInputType` | Source Input Type | text |
| `sourceQuery` | Source Query | text |