Documentation Index
Fetch the complete documentation index at: https://info.bundle.social/llms.txt
Use this file to discover all available pages before exploring further.
TikTok is the place for short-form video. The API has specific restrictions around music, privacy, and image formats that will surprise you.
Supported Content Types
- Videos: 1 video, up to 10 minutes. The bread and butter.
- Photo Mode (Images): 1-10 images. JPG, JPEG, or WebP only. Max 20 MB per image. PNG will be rejected.
Quirks & Gotchas
Privacy Levels & Permalinks
If you set a video’s privacy to SELF_ONLY (Private), the API cannot return a public permalink immediately.
- The
permalink field will be null or internal-only.
- We can’t give you a link to something that doesn’t publicly exist. Physics still applies.
Music & Copyright
TikTok is extremely strict about music rights.
- Commercial Music Library (CML): We expose TikTok’s pre-cleared music via TikTok Music: trending tracks, genres, and
song_clip_id for publish. No copyright roulette.
- Trending Audio: You generally cannot use TikTok’s in-app “trending audio” library directly via API.
- Royalty-Free: You can use the
autoAddMusic flag to let TikTok assign royalty-free music, but you lose control over the specific track. It’s a gamble.
- Best Practice: Use CML for controlled music, or burn your audio into the video file before uploading.
TikTok accepts JPG, JPEG, and WebP files for Photo Mode posts. PNG and other formats will be rejected. Convert before uploading. Each image must be under 20 MB.
Image sizing (Photo Mode)
For IMAGE posts, if photos are larger than 1920x1080 (or unusually tall/wide relative to that canvas), we may auto-scale them server-side so delivery matches what TikTok expects. You do not need to pre-shrink assets in every case. We handle the resizing when it helps.
The REVIEW Status
TikTok is the most common platform to put posts into a REVIEW status. This means TikTok wants to review the content before publishing. We periodically re-check and re-attempt publishing. Tell your users to be patient.
See Platform Limits for the full breakdown.
Text & Field Limits
| Field | Limit |
|---|
text | Max 2,200 characters |
Post Options
| Field | Type | Description |
|---|
type | VIDEO | IMAGE | Defaults to VIDEO. IMAGE is TikTok Photo Mode. |
text | string | Caption text. Max 2,200 characters. |
uploadIds | string[] | One video, or 1-10 Photo Mode images. |
thumbnail | string | URL to an uploaded thumbnail image. |
privacy | SELF_ONLY | PUBLIC_TO_EVERYONE | MUTUAL_FOLLOW_FRIENDS | FOLLOWER_OF_CREATOR | TikTok visibility setting. |
photoCoverIndex | number | Zero-based cover image index for Photo Mode. |
isBrandContent | boolean | Paid partnership promoting a third-party business. |
isOrganicBrandContent | boolean | Content promoting the creator’s own business. |
disableComments | boolean | Disable comments. |
disableDuet | boolean | Disable Duets. |
disableStitch | boolean | Disable Stitches. |
thumbnailOffset | number | Video cover frame offset in milliseconds. |
isAiGenerated | boolean | Mark AI-generated content. |
autoAddMusic | boolean | Let TikTok add music to Photo Mode posts. |
autoScale | boolean | For IMAGE posts only. Scale oversized images server-side. |
uploadToDraft | boolean | Upload as TikTok draft/inbox item. |
musicSoundInfo | object | CML music settings. See TikTok Music. |
Use uploadToDraft only when the user really wants TikTok draft handling. Draft uploads can cause massive publish delays. The video might show up in minutes, or it might take hours.TikTok’s answer is traffic: some days are faster, some days are worse. If your product needs predictable publishing, publish directly instead of using drafts.
{
"teamId": "team_123",
"title": "TikTok launch video",
"status": "SCHEDULED",
"postDate": "2026-06-01T15:00:00.000Z",
"socialAccountTypes": ["TIKTOK"],
"data": {
"TIKTOK": {
"type": "VIDEO",
"text": "Launch day",
"uploadIds": ["upl_vid_1"],
"privacy": "PUBLIC_TO_EVERYONE",
"disableComments": false,
"disableDuet": false,
"disableStitch": false,
"isAiGenerated": false
}
}
}
Analytics
For general analytics concepts (refresh rates, data retention, what “Returns 0” means), see the Analytics Overview.
TikTok provides detailed analytics data: demographics, audience splits, watch metrics, the works. Check the raw analytics for the detailed breakdowns.
Profile Analytics
Period: Rolling window (30 days). Aggregated from daily metrics.
| Metric | Description | Note |
|---|
impressions | Video views | |
impressionsUnique | Unique video views | |
views | Video views | Same as impressions for TikTok |
viewsUnique | Unique video views | Same as impressionsUnique |
likes | Total likes | Aggregated across all videos |
comments | Total comments | |
postCount | Total videos | |
followers | Followers | |
following | Following | |
Post Analytics
Period: Lifetime (Snapshot).
| Metric | Description | Note |
|---|
impressions | Video views | |
impressionsUnique | Unique views | TikTok doesn’t always distinguish; can equal impressions |
views | Video views | Same as impressions |
viewsUnique | Unique views | Same as impressionsUnique |
likes | Likes | |
comments | Comments | |
shares | Shares | |
saves | - | Returns 0 (not provided by TikTok API) |
Quirks
- Profile analytics aggregate daily metrics over a 30-day window.
- Post analytics are lifetime values.
- TikTok can take up to 48 hours to process some detailed analytics like audience demographics.
- Views and unique views are tracked separately but can sometimes be 0 if the platform decides so.
Raw Analytics - Demographics & Audience Data
TikTok provides audience and engagement data via raw analytics. Here’s what the raw payload looks like when enabled for your organization:
Account-Level Raw Data
{
"followers_count": 125400,
"following_count": 342,
"total_likes": 2891000,
"videos_count": 287,
"unique_video_views": 1450000,
"video_views": 8920000,
"comments": 45200,
"audience_ages": [
{ "age_range": "18-24", "percentage": 42.3 },
{ "age_range": "25-34", "percentage": 31.7 },
{ "age_range": "35-44", "percentage": 14.2 },
{ "age_range": "45-54", "percentage": 7.1 },
{ "age_range": "55+", "percentage": 4.7 }
],
"audience_cities": [
{ "city": "Los Angeles", "percentage": 8.2 },
{ "city": "New York", "percentage": 7.1 },
{ "city": "London", "percentage": 5.4 }
],
"engaged_audience": [
{ "metric": "likes", "value": 89200 },
{ "metric": "comments", "value": 4520 },
{ "metric": "shares", "value": 12300 }
],
"metrics": [
{
"date": "2026-01-15",
"new_followers": 234,
"video_views": 45600,
"profile_views": 1230,
"likes": 3400,
"comments": 120,
"shares": 890
}
]
}
Video-Level Raw Data
{
"item_id": "7123456789",
"caption": "My viral video",
"video_views": 1200000,
"likes": 89000,
"comments": 4500,
"shares": 12000,
"average_time_watched": 18.4,
"full_video_watched_rate": 0.42,
"total_time_watched": 22080000,
"reach": 890000,
"impression_sources": [
{ "source": "For You", "percentage": 72.1 },
{ "source": "Following", "percentage": 15.3 },
{ "source": "Search", "percentage": 8.4 }
],
"audience_genders": [
{ "gender": "Male", "percentage": 45.2 },
{ "gender": "Female", "percentage": 52.1 },
{ "gender": "Other", "percentage": 2.7 }
],
"audience_countries": [
{ "country": "US", "percentage": 35.2 },
{ "country": "GB", "percentage": 12.4 },
{ "country": "BR", "percentage": 8.9 }
]
}
TikTok raw data includes impression sources (For You, Following, Search), watch-through rates, audience gender/country splits, and daily metrics breakdowns. This is gold for content strategy - use it.
