> 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/documentation/api-and-references/tiktok.md).

# TikTok

The Pullbay TikTok API provides programmatic access to public TikTok data — user profiles, posts, comments, replies, hashtags, and keyword search. Integrate TikTok monitoring into your applications, dashboards, and analytics pipelines without scraping or maintaining your own TikTok session.

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

## Overview

The TikTok service lets you:

* Look up a user profile by handle
* Fetch the posts published by a given user
* Fetch a single post by its numeric ID or by its full URL
* Fetch comments on a post, and replies to a specific comment
* Search posts by keyword
* Look up a hashtag profile by name

All endpoints are read-only `GET` requests against public TikTok data — you don't need a TikTok account of your own.

## Common Use Cases

**Trend Research** — Use Search Posts with a keyword to see what's circulating right now, then pull engagement metrics (`views`, `likes`, `shares`) to gauge how a trend is performing.

**Hashtag & Campaign Tracking** — Use Get Hashtag by Name to monitor total view counts on a branded or campaign hashtag over time.

**Creator & Competitor Analysis** — Use Get User by Handle and Get User's Posts to track a creator's or competitor's posting cadence, follower growth, and per-post performance.

**Conversation & Sentiment Monitoring** — Use Get Post Comments and Get Comment Replies to pull the conversation under a post and feed comment text into your own sentiment-analysis or moderation pipeline.

**Content Archiving & Reporting** — Resolve posts by ID or by URL to attach canonical TikTok metadata (caption, stats, channel) to internal reports or dashboards.

## 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/{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           | Cursor / maxItems |
| `GET /tiktok/post`                                   | Get a post by URL             | —                 |
| `GET /tiktok/hashtag/handle/{name}`                  | Get a hashtag by name         | —                 |

***

### Get User by Handle

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

**Request**

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

**Parameters**

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

**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 }
}
```

**Response Schema**

| Field                    | Type   | Description                                                      |
| ------------------------ | ------ | ---------------------------------------------------------------- |
| `data`                   | array  | Array containing a single [User object](#user-object-tiktokuser) |
| `pricing.creditsCharged` | number | Credits charged for this request                                 |

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. No published flat rate.

***

### Get User's Posts

Returns posts published by a TikTok user. Use `cursor` to paginate, or `maxItems` for a one-shot bulk pull — the two are mutually exclusive.

**Request**

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

**Parameters**

| Parameter  | Type    | Required   | Default | Description                                                                                                             |
| ---------- | ------- | ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `id`       | string  | Yes (path) | —       | TikTok user ID, 1–100 characters                                                                                        |
| `region`   | string  | No         | —       | 2–5 character region/country code. The spec does not document a fixed enum for this field — treat it as an open string. |
| `maxItems` | integer | No         | —       | One-shot bulk pull, 1–200 results                                                                                       |
| `cursor`   | string  | No         | —       | Pagination cursor returned by a previous call                                                                           |

**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 }
}
```

**Response Schema**

| Field                                          | Type                       | Description                                                     |
| ---------------------------------------------- | -------------------------- | --------------------------------------------------------------- |
| `data`                                         | array                      | Array of [Post objects](#post-object-tiktokpost)                |
| `pagination.cursor` / `pagination.hasNextPage` | string / boolean, nullable | Cursor for the next page and whether more results are available |
| `pricing.creditsCharged`                       | number                     | Credits charged for this request                                |

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. No published flat rate.

***

### Get Post by ID

Returns a single TikTok post by its numeric ID.

> **Note:** there are two distinct ways to fetch a single post — by numeric ID (this endpoint, `GET /tiktok/post/{id}`) or by full URL (`GET /tiktok/post`, documented separately below). They are different operations with different parameters; pick the one that matches the data you already have on hand.

**Request**

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

**Parameters**

| Parameter | Type   | Required   | Default | Description                                                          |
| --------- | ------ | ---------- | ------- | -------------------------------------------------------------------- |
| `id`      | string | Yes (path) | —       | Numeric TikTok post ID, 1–50 characters                              |
| `region`  | string | No         | —       | 2–5 character region/country code. No documented enum — open string. |

**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 }
}
```

**Response Schema**

| Field                    | Type   | Description                                                      |
| ------------------------ | ------ | ---------------------------------------------------------------- |
| `data`                   | array  | Array containing a single [Post object](#post-object-tiktokpost) |
| `pricing.creditsCharged` | number | Credits charged for this request                                 |

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. No published flat rate.

***

### Get Post Comments

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

**Request**

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

**Parameters**

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

**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 }
}
```

**Response Schema**

| Field                                          | Type                       | Description                                                     |
| ---------------------------------------------- | -------------------------- | --------------------------------------------------------------- |
| `data`                                         | array                      | Array of [Comment objects](#comment-object-tiktokcomment)       |
| `pagination.cursor` / `pagination.hasNextPage` | string / boolean, nullable | Cursor for the next page and whether more results are available |
| `pricing.creditsCharged`                       | number                     | Credits charged for this request                                |

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. No published flat rate.

***

### 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**

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

**Parameters**

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

**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 }
}
```

**Response Schema**

| Field                                          | Type                       | Description                                                     |
| ---------------------------------------------- | -------------------------- | --------------------------------------------------------------- |
| `data`                                         | array                      | Array of [Comment objects](#comment-object-tiktokcomment)       |
| `pagination.cursor` / `pagination.hasNextPage` | string / boolean, nullable | Cursor for the next page and whether more results are available |
| `pricing.creditsCharged`                       | number                     | Credits charged for this request                                |

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. No published flat rate.

***

### Search TikTok Posts

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

**Request**

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

**Parameters**

| Parameter   | Type    | Required | Default | Description                                                                                                                                                                 |
| ----------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `keyword`   | string  | Yes      | —       | Search term, 1–100 characters                                                                                                                                               |
| `region`    | string  | No       | —       | 2–5 character region/country code. No documented enum — open string.                                                                                                        |
| `dateRange` | string  | No       | —       | A date-range filter string. The spec does not document a fixed set of accepted values for this field — treat it as open/undocumented rather than assuming specific options. |
| `sortType`  | string  | No       | —       | A sort-order string. The spec does not document a fixed set of accepted values for this field — treat it as open/undocumented rather than assuming specific options.        |
| `maxItems`  | integer | No       | —       | One-shot bulk pull, 1–200 results                                                                                                                                           |
| `cursor`    | string  | No       | —       | Pagination cursor returned by a previous call                                                                                                                               |

**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 }
}
```

**Response Schema**

| Field                                          | Type                       | Description                                                     |
| ---------------------------------------------- | -------------------------- | --------------------------------------------------------------- |
| `data`                                         | array                      | Array of [Post objects](#post-object-tiktokpost)                |
| `pagination.cursor` / `pagination.hasNextPage` | string / boolean, nullable | Cursor for the next page and whether more results are available |
| `pricing.creditsCharged`                       | number                     | Credits charged for this request                                |

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. No published flat rate.

***

### Get Post by URL

Returns a single TikTok post by its full URL.

> **Note:** this is a distinct operation from [Get Post by ID](#get-post-by-id) above. It hits the bare `/tiktok/post` path with no path parameter, taking `url` as a query parameter instead — useful when you have a TikTok link (copied from the app or scraped off the web) but haven't extracted the numeric post ID from it.

**Request**

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

**Parameters**

| Parameter | Type   | Required | Default | 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 }
}
```

**Response Schema**

| Field                    | Type   | Description                                                      |
| ------------------------ | ------ | ---------------------------------------------------------------- |
| `data`                   | array  | Array containing a single [Post object](#post-object-tiktokpost) |
| `pricing.creditsCharged` | number | Credits charged for this request                                 |

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. No published flat rate.

***

### Get Hashtag by Name

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

**Request**

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

**Parameters**

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

**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 }
}
```

**Response Schema**

| Field                    | Type   | Description                                                               |
| ------------------------ | ------ | ------------------------------------------------------------------------- |
| `data`                   | array  | Array containing a single [Hashtag object](#hashtag-object-tiktokhashtag) |
| `pricing.creditsCharged` | number | Credits charged for this request                                          |

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. No published flat rate.

***

## 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 or invalid parameters |
| `402`  | Insufficient credits                        |
| `404`  | User, post, comment, or hashtag not found   |

## Object Schema

### 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                         |
| `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 |

## Finding User and Post IDs

* **User ID**: returned as `id` from `GET /tiktok/user/handle/{username}`. You need this numeric ID to call `GET /tiktok/user/{id}/posts`.
* **Post ID**: the long numeric segment in a TikTok video URL, e.g. `https://www.tiktok.com/@tiktok/video/7636131611674692894` → `7636131611674692894`. If you only have the URL and not the extracted ID, pass the full URL to `GET /tiktok/post` instead — no need to parse it yourself.
* **Comment ID**: returned as `id` on each item in the response from `GET /tiktok/post/{id}/comments`; required as `commentId` to fetch that comment's replies.
* **Hashtag name**: the text after `#` on a TikTok hashtag page, without the `#` (e.g. `fyp`).

## Python Example

This example fetches a user's posts a page at a time using `cursor`-based pagination, stopping when `pagination.hasNextPage` is falsy or a page cap is reached:

```python
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://dashboard.pullbay.com/api"

def get_all_user_posts(user_id, region="US", max_pages=10):
    all_posts = []
    cursor = None
    for _ in range(max_pages):
        params = {"region": region}
        if cursor:
            params["cursor"] = cursor
        resp = requests.get(
            f"{BASE_URL}/tiktok/user/{user_id}/posts",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params=params,
        )
        resp.raise_for_status()
        body = resp.json()
        all_posts.extend(body["data"])
        pagination = body.get("pagination") or {}
        cursor = pagination.get("cursor")
        if not pagination.get("hasNextPage") or not cursor:
            break
    return all_posts

posts = get_all_user_posts("107955")
print(f"Fetched {len(posts)} posts")
```

Each request is billed independently, with the charged amount reported in that response's `pricing.creditsCharged` — there's no separate "fetch everything in one call" endpoint, so a multi-page pull like this makes one request per page.

## FAQ

<details>

<summary>How do I find a TikTok user's numeric ID?</summary>

Call `GET /tiktok/user/handle/{username}` with the user's handle (without `@`). The response's `id` field is the numeric user ID you need for `GET /tiktok/user/{id}/posts`.

</details>

<details>

<summary>What values does `region` accept?</summary>

The spec constrains it to a 2–5 character string but does not document a fixed list of accepted values. Pass whatever region/country code your use case requires; the API does not validate it against a published allow-list.

</details>

<details>

<summary>What values do `dateRange` and `sortType` accept on Search Posts?</summary>

The spec leaves both genuinely undocumented — there is no enum or pattern defined for either field. Don't assume specific option strings (like a fixed set of date windows or sort orders); if you need a particular behavior, test the value against the live API rather than relying on documentation that doesn't exist yet.

</details>

<details>

<summary>What's the difference between Get Post by ID and Get Post by URL?</summary>

They're two separate endpoints for the same underlying lookup. `GET /tiktok/post/{id}` takes the numeric post ID as a path parameter. `GET /tiktok/post` takes the full post URL as a query parameter (`url`) on the bare path, with no path parameter at all. Use whichever identifier you already have.

</details>

<details>

<summary>How do I paginate through comments or search results?</summary>

Use `cursor` (pass the value from the previous response's `pagination.cursor`) or `maxItems` for a single bulk pull — the two are mutually exclusive. Stop paging when `pagination.hasNextPage` is falsy.

</details>

<details>

<summary>What's the credit cost per request?</summary>

It's dynamic — every response includes `pricing.creditsCharged` with the exact amount for that call. There's no fixed published rate per endpoint or per result.

</details>

## Next Steps

* [**API Integration Guide**](broken://pages/68e75ab1a73d266350bd68301be87ff97cad563e) — integrate the Pullbay API into your backend application.
* [**n8n Integration Guide**](broken://pages/4308164455b56bbc694cf74c9768ea689c2fe719) — set up automated workflows using n8n with no coding required.
* [**Services Overview**](broken://pages/0d55376cbcca70097a683a71a593d3077825dbf1) — explore all available Pullbay services.


---

# 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/documentation/api-and-references/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.