> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/api-reference/endpoints/tiktok.md).

# TikTok

TikTok: users, posts, comments, hashtags, and search. All endpoints are read-only `GET` requests and return public TikTok data — no account of your own is required.

**Base URL:** `https://dashboard.pullbay.com/api`

## Endpoints

| Endpoint                                             | Description                    | Pagination        |
| ---------------------------------------------------- | ------------------------------ | ----------------- |
| `GET /tiktok/user/handle/{username}`                 | Get a user by handle           | —                 |
| `GET /tiktok/user/{id}/posts`                        | Get posts published by a user  | Cursor / maxItems |
| `GET /tiktok/post/{id}`                              | Get a post by ID               | —                 |
| `GET /tiktok/post`                                   | Get a post by URL              | —                 |
| `GET /tiktok/post/{id}/comments`                     | Get comments on a post         | Cursor / maxItems |
| `GET /tiktok/post/{id}/comments/{commentId}/replies` | Get replies to a comment       | Cursor / maxItems |
| `GET /tiktok/post/search`                            | Search TikTok posts by keyword | Cursor / maxItems |
| `GET /tiktok/hashtag/handle/{name}`                  | Get a hashtag by name          | —                 |

***

## Users

### Get User by Handle

Returns a TikTok user profile by handle (without `@`).

**Request**

```http
GET /tiktok/user/handle/{username}
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter  | Type   | Required | Description                                                 |
| ---------- | ------ | -------- | ----------------------------------------------------------- |
| `username` | string | Yes      | TikTok handle without `@` (e.g. `tiktok`), 1–100 characters |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/tiktok/user/handle/tiktok" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": "107955",
      "username": "tiktok",
      "nickname": "TikTok",
      "url": "https://www.tiktok.com/@tiktok",
      "bio": "One TikTok can make a big impact",
      "bioUrl": "https://linktr.ee/tiktok",
      "avatar": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/avatar.jpg",
      "verified": true,
      "profileCategory": "",
      "followers": 89000000,
      "following": 7,
      "likes": 1300000000,
      "videos": 1100
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`.

### Get User's Posts

Returns posts published by a TikTok user. Use `cursor` to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive). `region` may bias results toward a specific country (e.g. `US`).

**Request**

```http
GET /tiktok/user/{id}/posts
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter  | Type    | Required                   | Description                                                   |
| ---------- | ------- | -------------------------- | ------------------------------------------------------------- |
| `id`       | string  | Yes                        | TikTok user ID, 1–100 characters                              |
| `region`   | string  | No                         | 2–5 character region/country code to bias results (e.g. `US`) |
| `cursor`   | string  | One of `cursor`/`maxItems` | Pagination cursor returned by a previous call                 |
| `maxItems` | integer | One of `cursor`/`maxItems` | One-shot bulk pull, 1–200 results                             |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/tiktok/user/107955/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d region=US \
  -d maxItems=20
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": "7636131611674692894",
      "title": "Check this out!",
      "postPage": "https://www.tiktok.com/@tiktok/video/7636131611674692894",
      "uploadedAt": 1714560000,
      "uploadedAtFormatted": "2024-05-01T00:00:00Z",
      "views": 750000,
      "likes": 12500,
      "comments": 793,
      "shares": 1250,
      "bookmarks": 320,
      "poi": null,
      "channel": {
        "id": "107955",
        "username": "tiktok",
        "name": "TikTok",
        "bio": "One TikTok can make a big impact",
        "avatar": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/avatar.jpg"
      },
      "collabInfo": {},
      "video": {},
      "song": {},
      "hashtags": [],
      "subtitleInformation": []
    }
  ],
  "pagination": { "page": null, "hasNextPage": null, "cursor": null, "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Cost scales with the number of posts returned, not the number of requests.

***

## Posts

### Get Post by ID

Returns a single TikTok post by its numeric ID.

> **Note:** there are two ways to fetch a single post — by numeric ID (this endpoint) or by full URL (`GET /tiktok/post`, below). Use whichever you already have on hand; both return the same `TiktokPost` object.

**Request**

```http
GET /tiktok/post/{id}
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter | Type   | Required | Description                             |
| --------- | ------ | -------- | --------------------------------------- |
| `id`      | string | Yes      | Numeric TikTok post ID, 1–50 characters |
| `region`  | string | No       | 2–5 character region/country code       |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/tiktok/post/7636131611674692894" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d region=US
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": "7636131611674692894",
      "title": "Check this out!",
      "postPage": "https://www.tiktok.com/@tiktok/video/7636131611674692894",
      "uploadedAt": 1714560000,
      "uploadedAtFormatted": "2024-05-01T00:00:00Z",
      "views": 750000,
      "likes": 12500,
      "comments": 793,
      "shares": 1250,
      "bookmarks": 320,
      "poi": null,
      "channel": {
        "id": "107955",
        "username": "tiktok",
        "name": "TikTok",
        "bio": "One TikTok can make a big impact",
        "avatar": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/avatar.jpg"
      },
      "collabInfo": {},
      "video": {},
      "song": {},
      "hashtags": [],
      "subtitleInformation": []
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`.

### Get Post by URL

Returns a single TikTok post by its full URL.

> **Note:** this is the second of the two ways to fetch a single post — see [Get Post by ID](#get-post-by-id) above. Handy if you scraped a link off TikTok and never extracted the numeric ID.

**Request**

```http
GET /tiktok/post
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter | Type   | Required | Description                                                                                               |
| --------- | ------ | -------- | --------------------------------------------------------------------------------------------------------- |
| `url`     | string | Yes      | Full TikTok post URL, 1–2048 characters (e.g. `https://www.tiktok.com/@tiktok/video/7636131611674692894`) |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/tiktok/post" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d url="https://www.tiktok.com/@tiktok/video/7636131611674692894"
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": "7636131611674692894",
      "title": "Check this out!",
      "postPage": "https://www.tiktok.com/@tiktok/video/7636131611674692894",
      "uploadedAt": 1714560000,
      "uploadedAtFormatted": "2024-05-01T00:00:00Z",
      "views": 750000,
      "likes": 12500,
      "comments": 793,
      "shares": 1250,
      "bookmarks": 320,
      "poi": null,
      "channel": {
        "id": "107955",
        "username": "tiktok",
        "name": "TikTok",
        "bio": "One TikTok can make a big impact",
        "avatar": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/avatar.jpg"
      },
      "collabInfo": {},
      "video": {},
      "song": {},
      "hashtags": [],
      "subtitleInformation": []
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`.

***

## Comments

### Get Post Comments

Returns comments on a TikTok post. Use `cursor` to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive).

**Request**

```http
GET /tiktok/post/{id}/comments
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter  | Type    | Required                   | Description                                   |
| ---------- | ------- | -------------------------- | --------------------------------------------- |
| `id`       | string  | Yes                        | TikTok post ID, 1–100 characters              |
| `cursor`   | string  | One of `cursor`/`maxItems` | Pagination cursor returned by a previous call |
| `maxItems` | integer | One of `cursor`/`maxItems` | One-shot bulk pull, 1–500 results             |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/tiktok/post/7636131611674692894/comments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d maxItems=50
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": "7636187917325304607",
      "awemeId": "7636131611674692894",
      "text": "Love this!",
      "createdAt": "2026-05-05T19:46:32.000Z",
      "likeCount": 25,
      "replyCount": 3,
      "commentLanguage": "en",
      "isAuthorLiked": false,
      "user": {
        "id": "12345",
        "username": "someuser",
        "nickname": "Some User",
        "avatar": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/avatar2.jpg",
        "verified": false
      }
    }
  ],
  "pagination": { "page": null, "hasNextPage": null, "cursor": null, "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Cost scales with the number of comments returned, not the number of requests.

### Get Comment Replies

Returns replies to a specific TikTok comment. Use `cursor` to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive).

**Request**

```http
GET /tiktok/post/{id}/comments/{commentId}/replies
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter   | Type    | Required                   | Description                                   |
| ----------- | ------- | -------------------------- | --------------------------------------------- |
| `id`        | string  | Yes                        | TikTok post ID, 1–100 characters              |
| `commentId` | string  | Yes                        | ID of the parent comment, 1–100 characters    |
| `cursor`    | string  | One of `cursor`/`maxItems` | Pagination cursor returned by a previous call |
| `maxItems`  | integer | One of `cursor`/`maxItems` | One-shot bulk pull, 1–500 results             |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/tiktok/post/7636131611674692894/comments/7636187917325304607/replies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d maxItems=50
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": "7636187917325304608",
      "parentId": "7636187917325304607",
      "awemeId": "7636131611674692894",
      "text": "Totally agree!",
      "createdAt": "2026-05-05T20:01:12.000Z",
      "likeCount": 4,
      "commentLanguage": "en",
      "isAuthorLiked": false,
      "user": {
        "id": "67890",
        "username": "anotheruser",
        "nickname": "Another User",
        "avatar": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/avatar3.jpg",
        "verified": false
      }
    }
  ],
  "pagination": { "page": null, "hasNextPage": null, "cursor": null, "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Cost scales with the number of replies returned, not the number of requests.

***

## Hashtags & Search

### Search Posts

Search TikTok posts by keyword. Use `cursor` to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive).

**Request**

```http
GET /tiktok/post/search
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter   | Type    | Required                   | Description                                       |
| ----------- | ------- | -------------------------- | ------------------------------------------------- |
| `keyword`   | string  | Yes                        | Search term, 1–100 characters                     |
| `region`    | string  | No                         | 2–5 character region/country code to bias results |
| `dateRange` | string  | No                         | Restricts results to a date range                 |
| `sortType`  | string  | No                         | Sort order for results                            |
| `cursor`    | string  | One of `cursor`/`maxItems` | Pagination cursor returned by a previous call     |
| `maxItems`  | integer | One of `cursor`/`maxItems` | One-shot bulk pull, 1–200 results                 |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/tiktok/post/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d keyword="cooking hacks" \
  -d region=US \
  -d maxItems=20
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": "7636131611674692894",
      "title": "Check this out!",
      "postPage": "https://www.tiktok.com/@tiktok/video/7636131611674692894",
      "uploadedAt": 1714560000,
      "uploadedAtFormatted": "2024-05-01T00:00:00Z",
      "views": 750000,
      "likes": 12500,
      "comments": 793,
      "shares": 1250,
      "bookmarks": 320,
      "poi": null,
      "channel": {
        "id": "107955",
        "username": "tiktok",
        "name": "TikTok",
        "bio": "One TikTok can make a big impact",
        "avatar": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/avatar.jpg"
      },
      "collabInfo": {},
      "video": {},
      "song": {},
      "hashtags": [],
      "subtitleInformation": []
    }
  ],
  "pagination": { "page": null, "hasNextPage": null, "cursor": null, "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Cost scales with the number of results returned, not the number of requests.

### Get Hashtag by Name

Returns a TikTok hashtag profile by name (without `#`).

**Request**

```http
GET /tiktok/hashtag/handle/{name}
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter | Type   | Required | Description                                             |
| --------- | ------ | -------- | ------------------------------------------------------- |
| `name`    | string | Yes      | Hashtag name without `#` (e.g. `fyp`), 1–100 characters |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/tiktok/hashtag/handle/fyp" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": "12345",
      "name": "fyp",
      "views": 1234567890
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`.

***

## Object schemas

### User object (`TiktokUser`)

| Field             | Type    | Description                           |
| ----------------- | ------- | ------------------------------------- |
| `id`              | string  | TikTok user ID                        |
| `username`        | string  | TikTok handle (without `@`)           |
| `nickname`        | string  | Display name                          |
| `url`             | string  | Profile URL                           |
| `bio`             | string  | Bio text                              |
| `bioUrl`          | string  | Link in bio                           |
| `avatar`          | string  | Avatar image URL                      |
| `verified`        | boolean | Whether the account is verified       |
| `profileCategory` | string  | Profile category, if set              |
| `followers`       | integer | Follower count                        |
| `following`       | integer | Following count                       |
| `likes`           | integer | Total likes received across all posts |
| `videos`          | integer | Total number of posts                 |

### Post object (`TiktokPost`)

| Field                 | Type               | Description                                      |
| --------------------- | ------------------ | ------------------------------------------------ |
| `id`                  | string             | TikTok post ID                                   |
| `title`               | string             | Post caption/title                               |
| `postPage`            | string             | URL of the post                                  |
| `uploadedAt`          | integer            | Upload time, Unix timestamp in seconds           |
| `uploadedAtFormatted` | string (date-time) | Upload time, ISO 8601                            |
| `views`               | integer            | View count                                       |
| `likes`               | integer            | Like count                                       |
| `comments`            | integer            | Comment count                                    |
| `shares`              | integer            | Share count                                      |
| `bookmarks`           | integer            | Bookmark (save) count                            |
| `poi`                 | object, nullable   | Point-of-interest tag, if present                |
| `channel`             | object             | Post author — see Post Channel object below      |
| `collabInfo`          | object             | Collaborator info, if the post is a collab       |
| `video`               | object             | Video asset details (URLs, resolution, duration) |
| `song`                | object             | Sound/music details                              |
| `hashtags`            | array              | Hashtags used in the post                        |
| `subtitleInformation` | array              | Available subtitle/caption tracks                |

### Post Channel object (`TiktokPostChannel`)

Lightweight author reference embedded in `TiktokPost.channel`.

| Field      | Type   | Description                 |
| ---------- | ------ | --------------------------- |
| `id`       | string | TikTok user ID              |
| `username` | string | TikTok handle (without `@`) |
| `name`     | string | Display name                |
| `bio`      | string | Bio text                    |
| `avatar`   | string | Avatar image URL            |

### Comment object (`TiktokComment`)

Used for both top-level comments and replies.

| Field             | Type               | Description                                                         |
| ----------------- | ------------------ | ------------------------------------------------------------------- |
| `id`              | string             | Comment ID                                                          |
| `parentId`        | string             | Parent comment ID — present only on replies                         |
| `awemeId`         | string             | ID of the post the comment was made on                              |
| `text`            | string             | Comment text                                                        |
| `createdAt`       | string (date-time) | When the comment was posted                                         |
| `likeCount`       | integer            | Like count                                                          |
| `replyCount`      | integer            | Number of replies — present only on top-level comments              |
| `commentLanguage` | string             | Detected language code                                              |
| `isAuthorLiked`   | boolean            | Whether the post author liked this comment                          |
| `user`            | object             | Commenter info (`id`, `username`, `nickname`, `avatar`, `verified`) |

### Hashtag object (`TiktokHashtag`)

| Field   | Type    | Description                                         |
| ------- | ------- | --------------------------------------------------- |
| `id`    | string  | Hashtag ID                                          |
| `name`  | string  | Hashtag name (without `#`)                          |
| `views` | integer | Total view count across all posts using the hashtag |

***

## Errors

All non-2xx responses share the same envelope:

```json
{
  "status": 400,
  "message": "Bad request",
  "success": false,
  "error": { "code": "BAD_REQUEST" }
}
```

| Status | Meaning                                   |
| ------ | ----------------------------------------- |
| `400`  | Bad request — missing/invalid parameters  |
| `402`  | Insufficient credits                      |
| `404`  | User, post, comment, or hashtag not found |

## Two Ways to Fetch a Post

If you already have a numeric post ID, use `GET /tiktok/post/{id}`. If you only have a TikTok link (e.g. copied from the app or scraped off the web), use `GET /tiktok/post?url=...` instead — both return the same `TiktokPost` object, so you don't need to parse the ID out of the URL yourself.

## Pagination Notes

* All four list endpoints (user posts, post comments, comment replies, post search) accept `cursor` and `maxItems` as mutually exclusive pagination strategies — pass `cursor` from a previous response to continue, or `maxItems` to pull a fixed batch in one call.
* `pagination.cursor` and `pagination.hasNextPage` in the response indicate whether more results are available.
* Single-item lookups (user by handle, post by ID/URL, hashtag by name) are never paginated.

## Finding User, Post, and Hashtag IDs

* **User ID**: returned as `id` from `GET /tiktok/user/handle/{username}`; required to fetch a user's posts.
* **Post ID**: the long numeric segment in a TikTok video URL, e.g. `https://www.tiktok.com/@tiktok/video/7636131611674692894` → `7636131611674692894`. Alternatively, pass the full URL to `GET /tiktok/post`.
* **Hashtag name**: the text after `#` in a TikTok hashtag page, without the `#` (e.g. `fyp`).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pullbay.com/api-reference/endpoints/tiktok.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.