Xpoz provides 10 TikTok tools across three categories: users, posts, and comments. TikTok is unique in having hashtag-specific search tools.
Available Fields
User Fields
These fields are available on all user tools (getTiktokUser, searchTiktokUsers, getTiktokUsersByKeywords, getTiktokUsersByHashtags).
Default: id, username, nickname
| Category | Fields |
|---|
| Identity | id, username, nickname, signature, secUid, avatar |
| Status | isPrivate, isVerified |
| Metrics | followerCount, followingCount, likeCount, postCount |
| Locale | language, region |
| Timestamps | createdAt, usernameModifyTime |
getTiktokUsersByKeywords and getTiktokUsersByHashtags also return aggregation fields: aggRelevance, relevantPostsCount, relevantPostsLikesSum, relevantPostsCommentsSum, relevantPostsPlaysSum, relevantPostsForwardsSum.
Post Fields
These fields are available on all post tools (getTiktokPostsByIds, getTiktokPostsByUser, getTiktokPostsByKeywords, getTiktokPostsByHashtags).
Default: id, description, username, createdAtDate
| Category | Fields |
|---|
| Core | id, postType, isPrivate, userId, username, nickname, description, descriptionLanguage, createdAt, createdAtTimestamp, createdAtDate |
| Engagement | collectCount, commentCount, likeCount, downloadCount, forwardCount, playCount |
| Media | videoThumbnail, videoUrl (array of video URLs), duration (video length in seconds) |
| Content | hashtags (array of hashtag strings), transcriptsJson |
getTiktokCommentsByPostId.
Default: id, text, username, createdAtDate
| Category | Fields |
|---|
| All | id, postId, userId, username, text, likeCount, createdAt, createdAtTimestamp, createdAtDate |
Always specify only the fields you need using the fields parameter. For example, ["id", "description", "playCount", "likeCount", "hashtags"] for content analysis. See Field Selection for details.
getTiktokUser
Get a single TikTok user profile by ID or username.
| Parameter | Type | Required | Description |
|---|
identifier | string | Yes | User ID (numeric) or username. |
identifierType | string | Yes | "id" or "username". |
fields | string[] | No | Fields to return. |
forceLatest | boolean | No | Force fresh data from API, bypassing cache. Default: false. |
For exact username lookups, use getTiktokUser. For name-based or fuzzy searches, use searchTiktokUsers instead.
searchTiktokUsers
Search TikTok users by name or username with real-time results.
| Parameter | Type | Required | Description |
|---|
name | string | Yes | Search query (name, partial username, or keywords). |
limit | number | No | Max results. Default: 10, max: 10. |
fields | string[] | No | Fields to return. |
This tool performs a real-time search. For exact username lookups, use getTiktokUser instead.
getTiktokUsersByKeywords
Search for users who authored TikTok posts matching keywords. Returns unique, deduplicated user profiles.
| Parameter | Type | Required | Description |
|---|
query | string | Yes | Full-text search of post descriptions. Max 250 characters. Supports exact phrases, boolean operators (AND, OR), and parentheses. |
responseType | string | No | "fast" (default), "paging", or "csv". See Response Modes. |
limit | number | No | Max results. Fast: capped at 300. Paging/CSV: max 500,000. |
startDate | string | No | Start date filter (YYYY-MM-DD). |
endDate | string | No | End date filter (YYYY-MM-DD). |
fields | string[] | No | Fields to return. Includes user fields plus aggregation fields. |
pageNumber | integer | No | Page to fetch (1-indexed). Requires tableName for pages > 1. |
pageNumberEnd | integer | No | End page for bulk fetching. Must be >= pageNumber. |
tableName | string | No | Cached table name from a previous pagination response. |
forceLatest | boolean | No | Force fresh data from API. Default: false. |
Search for users who posted content tagged with specific hashtags. Returns unique, deduplicated user profiles.
| Parameter | Type | Required | Description |
|---|
hashtags | string[] | Yes | Array of hashtags (1-5). Bare alphanumeric/underscore only — do not include #. OR semantics: matches users who posted with any of the listed hashtags. |
responseType | string | No | "fast" (default), "paging", or "csv". See Response Modes. |
limit | number | No | Max results. Fast: capped at 300. Paging/CSV: max 500,000. |
startDate | string | No | Start date filter (YYYY-MM-DD). |
endDate | string | No | End date filter (YYYY-MM-DD). |
fields | string[] | No | Fields to return. Includes user fields plus aggregation fields. |
pageNumber | integer | No | Page to fetch (1-indexed). Requires tableName for pages > 1. |
pageNumberEnd | integer | No | End page for bulk fetching. Must be >= pageNumber. |
tableName | string | No | Cached table name from a previous pagination response. |
forceLatest | boolean | No | Force fresh data from API. Default: false. |
hashtags values: ["dance", "fyp"], ["cooking"], ["sustainable_fashion"]
Pass bare alphanumeric tags only — no leading #. Each hashtag must match the pattern [A-Za-z0-9_] with a max length of 500 characters.
Post Tools
getTiktokPostsByIds
Get one or more TikTok posts by IDs (1-100 per request).
| Parameter | Type | Required | Description |
|---|
postIds | string[] | Yes | Array of numeric post IDs (1-100). Each must be digits only. |
fields | string[] | No | Fields to return. |
forceLatest | boolean | No | Force fresh data from API. Default: false. |
Data older than 3 days is automatically refreshed.
getTiktokPostsByUser
Get posts from a TikTok user by ID or username.
| Parameter | Type | Required | Description |
|---|
identifier | string | Yes | User ID (numeric) or username. |
identifierType | string | Yes | "id" or "username". |
responseType | string | No | "fast" (default), "paging", or "csv". See Response Modes. |
limit | number | No | Max results. Fast: capped at 300. Paging/CSV: max 500,000. |
startDate | string | No | Start date filter (YYYY-MM-DD). |
endDate | string | No | End date filter (YYYY-MM-DD). |
fields | string[] | No | Fields to return. |
pageNumber | integer | No | Page to fetch (1-indexed). |
pageNumberEnd | integer | No | End page for bulk fetching. |
tableName | string | No | Cached table name from a previous pagination response. |
forceLatest | boolean | No | Force fresh data from API. Default: false. |
Data older than 1 week is automatically refreshed.
getTiktokPostsByKeywords
Search TikTok posts by keywords in descriptions and video transcripts.
| Parameter | Type | Required | Description |
|---|
query | string | Yes | Full-text search of post descriptions. Max 250 characters. Supports exact phrases, boolean operators (AND, OR), and parentheses. |
responseType | string | No | "fast" (default), "paging", or "csv". See Response Modes. |
limit | number | No | Max results. Fast: capped at 300. Paging/CSV: max 500,000. |
startDate | string | No | Start date filter (YYYY-MM-DD). |
endDate | string | No | End date filter (YYYY-MM-DD). |
fields | string[] | No | Fields to return. |
pageNumber | integer | No | Page to fetch (1-indexed). |
pageNumberEnd | integer | No | End page for bulk fetching. |
tableName | string | No | Cached table name from a previous pagination response. |
forceLatest | boolean | No | Force fresh data from API. Default: false. |
For hashtag-based search, use getTiktokPostsByHashtags instead — it searches the indexed hashtags column directly, which is more precise than keyword search in descriptions.
getTiktokPostsByHashtags
Search TikTok posts by hashtags. Searches the indexed hashtags column directly (not post descriptions).
| Parameter | Type | Required | Description |
|---|
hashtags | string[] | Yes | Array of hashtags (1-5). Bare alphanumeric/underscore only — do not include #. OR semantics: matches posts containing any of the listed hashtags. |
responseType | string | No | "fast" (default), "paging", or "csv". See Response Modes. |
limit | number | No | Max results. Fast: capped at 300. Paging/CSV: max 500,000. |
startDate | string | No | Start date filter (YYYY-MM-DD). |
endDate | string | No | End date filter (YYYY-MM-DD). |
fields | string[] | No | Fields to return. |
pageNumber | integer | No | Page to fetch (1-indexed). |
pageNumberEnd | integer | No | End page for bulk fetching. |
tableName | string | No | Cached table name from a previous pagination response. |
forceLatest | boolean | No | Force fresh data from API. Default: false. |
hashtags values: ["dance", "fyp", "viral"], ["cooking"], ["sustainable_fashion"]
Pass bare alphanumeric tags only — no leading #. Each hashtag must match the pattern [A-Za-z0-9_] with a max length of 500 characters.
Use getTiktokPostsByHashtags for precise hashtag matching. Use getTiktokPostsByKeywords when searching for terms in post descriptions and transcripts.
Get comments for a TikTok post.
| Parameter | Type | Required | Description |
|---|
postId | string | Yes | TikTok post ID. |
responseType | string | No | "fast" (default), "paging", or "csv". See Response Modes. |
limit | number | No | Max results. Fast: capped at 300. Paging/CSV: max 500,000. |
startDate | string | No | Start date filter (YYYY-MM-DD). |
endDate | string | No | End date filter (YYYY-MM-DD). |
fields | string[] | No | Fields to return. |
pageNumber | integer | No | Page to fetch (1-indexed). |
pageNumberEnd | integer | No | End page for bulk fetching. |
tableName | string | No | Cached table name from a previous pagination response. |
forceLatest | boolean | No | Force fresh data from API. Default: false. |
Data older than 1 week is automatically refreshed.
