Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Parameters

Parameter
Type
Required
Default
Description

username

string

Yes

—

TikTok handle without @, 1–100 characters (e.g. tiktok)

Example

Response

Response Schema

Field
Type
Description

data

array

Array containing a single User object

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

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

Response

Response Schema

Field
Type
Description

data

array

Array of Post objects

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

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

Response

Response Schema

Field
Type
Description

data

array

Array containing a single Post object

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

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

Response

Response Schema

Field
Type
Description

data

array

Array of Comment objects

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

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

Response

Response Schema

Field
Type
Description

data

array

Array of Comment objects

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

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

Response

Response Schema

Field
Type
Description

data

array

Array of Post objects

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

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

Response

Response Schema

Field
Type
Description

data

array

Array containing a single Post object

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

Parameters

Parameter
Type
Required
Default
Description

name

string

Yes (path)

—

Hashtag name without #, 1–100 characters (e.g. fyp)

Example

Response

Response Schema

Field
Type
Description

data

array

Array containing a single Hashtag object

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:

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:

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

How do I find a TikTok user's numeric ID?

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.

What values does `region` accept?

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.

What values do `dateRange` and `sortType` accept on Search Posts?

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.

What's the difference between Get Post by ID and Get Post by URL?

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.

How do I paginate through comments or search results?

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.

What's the credit cost per request?

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.

Next Steps

  • API Integration Guide — integrate the Pullbay API into your backend application.

  • n8n Integration Guide — set up automated workflows using n8n with no coding required.

  • Services Overview — explore all available Pullbay services.

PreviousReddit
NextTwitter / X

Last updated