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

## 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://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 }
}
```

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

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

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

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

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

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

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

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

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.