> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindcase.co/llms.txt
> Use this file to discover all available pages before exploring further.

# TikTok Posts API

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

`POST /v1/data/tiktok/posts/run`

**Pricing:** $0.002 per post ($2.00 per 1,000).

## Ways to call it

* **Profile**: set `profiles` (optional: `resultsPerPage`)
* **Hashtag**: set `hashtags` (optional: `resultsPerPage`)
* **Keyword**: set `searchQueries` (optional: `resultsPerPage`)
* **Post URL**: set `postURLs`
* **Sound**: set `musics` (optional: `resultsPerPage`)

## Request

Send the inputs under `params`. Only the keys below are accepted; any other key returns `422 invalid_params`.

**profiles** `string`

TikTok username or handle to scrape posts from (with or without @).

Format e.g. `https://www.tiktok.com/@khaby.lame`.

**hashtags** `string`

Hashtag name to scrape posts for (without #).

**searchQueries** `string`

Free-text search query to find matching TikTok posts.

**postURLs** `string[]`

Direct TikTok video or post URLs to scrape, one per element.

**musics** `string`

TikTok music or sound page URL. Returns posts that use this sound.

Format e.g. `https://www.tiktok.com/music/sound-7670957197136399134`.

**resultsPerPage** `integer`

Number of posts to return. Use 0 for all.

Min `1`.

## Example

```bash cURL theme={null}
curl -X POST "https://api.mindcase.co/v1/data/tiktok/posts/run?wait=true" \
  -H "Authorization: Bearer $MINDCASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "params": {
    "profiles": "khaby.lame",
    "resultsPerPage": 15
  }
}'
```

```python Python theme={null}
import os, requests

r = requests.post(
    "https://api.mindcase.co/v1/data/tiktok/posts/run",
    params={"wait": "true"},
    headers={"Authorization": f"Bearer {os.environ['MINDCASE_API_KEY']}"},
    json={"params": {
    "profiles": "khaby.lame",
    "resultsPerPage": 15
}},
)
job = r.json()
rows = job.get("data", [])  # if job["status"] == "running", poll /v1/jobs/{job_id}/results
```

```javascript Node.js theme={null}
const r = await fetch("https://api.mindcase.co/v1/data/tiktok/posts/run?wait=true", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MINDCASE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ params: {
  "profiles": "khaby.lame",
  "resultsPerPage": 15
} }),
});
const job = await r.json();
const rows = job.data ?? []; // if job.status === "running", poll /v1/jobs/{job_id}/results
```

## Response fields

Each row in `data` is one post, keyed by these fields.

| Field | 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 |
| `photoSlideshowImageUrls` | Photo/Slideshow Image URLs | array |
| `thumbnail` | Thumbnail | image |
| `durationS` | Duration (s) | number |
| `resolution` | Resolution | text |
| `videoWidth` | Video Width | number |
| `videoHeight` | Video Height | number |
| `sound` | Sound | object |
| `location` | Location | text |
| `locationAddress` | Location Address | text |
| `country` | Country | text |
| `hashtagViews` | Hashtag Views | number |
| `sourceQuery` | Source Query | text |
| `videoId` | Video ID | text |

## Example response

Abridged: long text and lists are shortened.

```json theme={null}
{
  "job_id": "7f3a1c2e-0b9d-4c55-9a51-3f2e8d1b6a40",
  "agent": "tiktok/posts",
  "status": "completed",
  "row_count": 1,
  "truncated": false,
  "data": [
    {
      "isSlideshow": false,
      "author": {
        "profileUrl": "https://www.tiktok.com/@khaby.lame",
        "displayName": "Khabane lame",
        "avatar": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcenter:720:720.jpeg?dr=9640&refresh_token...",
        "bio": "Se vuoi ridere sei nel posto giusto😎 If u wanna laugh u r in the right place😎",
        "verified": true,
        "followers": 162700000,
        "following": 81,
        "mutualFollows": 77,
        "totalLikes": 2700000000,
        "likesGiven": 0,
        "videos": 1348,
        "businessAccount": false,
        "businessCategory": null,
        "tiktokSeller": false,
        "private": false,
        "accountCreated": "2016-08-10T22:02:34Z",
        "tiktokId": "127905465618821121"
      },
      "resolution": "720p",
      "effects": [],
      "slideshowImages": null,
      "saves": 80383,
      "sound": {
        "name": "original sound",
        "author": "Khabane lame",
        "id": "7670957197136399134",
        "original": true,
        "album": null,
        "videoCount": null,
        "audioUrl": "https://v16m.tiktokcdn-us.com/9f8c1f2b641628a10b42115d2b8041de/6a82e08e/video/tos/useast8/tos-useast8-v-27dcd7-tx2/o4EbAqLBfEcEU9FJtHEAcLCVFtAfSC90ABdEwD/?a=..."
      },
      "language": "en",
      "hashtagViews": null,
      "postedDate": "2026-08-06T16:32:00.000Z",
      "country": null,
      "locationAddress": null,
      "shares": 150800,
      "postUrl": "https://www.tiktok.com/@khaby.lame/video/7670957230178503966",
      "likes": 2100000,
      "views": 41200000,
      "photoSlideshowImageUrls": [],
      "comments": 34000,
      "isAd": false,
      "location": null,
      "mentions": [],
      "isSponsored": false,
      "sourceQuery": "khaby.lame",
      "thumbnail": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oIeLlIC7IVjqF3mbnech0IWJUwYteGXx6EIAAI~tplv-tiktokx-origin.image?dr=9636&x-expires=1787112000...",
      "hashtags": [
        {
          "name": "learnfromkhaby"
        },
        {
          "name": "comedy"
        }
      ]
    }
  ]
}
```

## Related APIs

For creator-level data use [`tiktok/profiles`](https://docs.mindcase.co/apis/tiktok/profiles); for the comments on a video use [`tiktok/comments`](https://docs.mindcase.co/apis/tiktok/comments).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.