> 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://api.pullbay.com/`

## 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://api.pullbay.com/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://api.pullbay.com/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://api.pullbay.com/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://api.pullbay.com/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://api.pullbay.com/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://api.pullbay.com/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://api.pullbay.com/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://api.pullbay.com/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`).