TikTok API Integration - Video Upload & Analytics

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

Image Format (Photo Mode)

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.

Media Limits

See Platform Limits for the full breakdown.

Text & Field Limits

Field	Limit
`text` (`VIDEO`)	Max 2,200 characters
`text` (`IMAGE`)	Max 4,000 characters
`title` (`IMAGE` only)	Max 90 characters
`locationName`	Max 255 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 for `VIDEO`, 4,000 for `IMAGE`.
`title`	`string`	`IMAGE` only. Title of the photo post, max 90 characters. Rejected on `VIDEO` posts with `title is available only for IMAGE type posts.`
`uploadIds`	`string[]`	One video, or 1-35 Photo Mode images.
`locationId`	`string`	Location tag shown on the post, from Location tags. `VIDEO` and `IMAGE`. Send together with `locationName`.
`locationName`	`string`	Name of the location tag, as returned with `locationId`. Send together with `locationId`.
`thumbnail`	`string`	VIDEO only. Custom cover: the `url` of an image uploaded to bundle.social (`POST /upload`). URLs hosted elsewhere are rejected with `400`, since TikTok only fetches covers from verified domains. JPG/PNG/WebP, 360x360 to 1080x1920, up to 20 MB. Overrides `thumbnailOffset`.
`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. Ignored when `thumbnail` is set.
`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
    }
  }
}

Posting Options of an Account

Endpoint: GET /api/v1/misc/tiktok/post-settings Returns the privacy levels, interaction settings and maximum video duration the connected TikTok account allows, read live from TikTok. Use it to build the options of your composer (which privacy values to offer, whether comments, Duets and Stitches can be turned on).

Param	Required	Description
`teamId`	Yes	Team with a connected TikTok account. The team must belong to your API key’s organization.

GET /api/v1/misc/tiktok/post-settings?teamId=team_123

{
  "privacyLevelOptions": ["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "SELF_ONLY"],
  "commentDisabled": false,
  "duetDisabled": false,
  "stitchDisabled": true,
  "maxVideoPostDurationSec": 600
}

Field	Description
`privacyLevelOptions`	Values the account accepts for `privacy`. Public accounts: `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, `SELF_ONLY`. Private accounts: `FOLLOWER_OF_CREATOR`, `MUTUAL_FOLLOW_FRIENDS`, `SELF_ONLY`.
`commentDisabled`	`true` when comments can’t be enabled (the creator allows comments from no one). Send `disableComments: true`.
`duetDisabled`	`true` when Duets can’t be enabled (Duets set to “Only you”, or a private account). Send `disableDuet: true`.
`stitchDisabled`	`true` when Stitches can’t be enabled (Stitches set to “Only you”, or a private account). Send `disableStitch: true`.
`maxVideoPostDurationSec`	Longest video, in seconds, the account can publish. Can be `null`. Longer videos fail at publish time.

A value the account doesn’t allow is not rejected when you create the post. It fails at publish time with TT:40002.

Each call counts against the account’s TikTok rate limit, so fetch it when building your composer, not before every publish. If TikTok returns incomplete settings, the endpoint returns 502.

Location Tags

Endpoint: GET /api/v1/misc/tiktok/locations Searches TikTok’s location tags for the team’s TikTok account. Put the chosen tag on a post with locationId and locationName.

Param	Required	Description
`teamId`	Yes	Team with a connected TikTok account.
`q`	Yes	Search text, 1 to 100 characters.

GET /api/v1/misc/tiktok/locations?teamId=team_123&q=warsaw

{
  "items": [
    { "locationId": "123456789", "name": "Warsaw", "address": "Poland" },
    { "locationId": "987654321", "name": "Warsaw Old Town", "address": "Rynek Starego Miasta, Warsaw, Poland" }
  ]
}

address can be a country, region, city or full street address, and can be null. Send both fields with the post; either one alone is rejected:

{ "TIKTOK": { "type": "VIDEO", "text": "Launch day", "uploadIds": ["upl_vid_1"], "privacy": "PUBLIC_TO_EVERYONE", "locationId": "123456789", "locationName": "Warsaw" } }

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,
      "audience_activity": [
        { "hour": "0", "count": 12 },
        { "hour": "1", "count": 18 }
      ]
    }
  ]
}

audience_activity is the hourly breakdown of when your followers are active on TikTok (UTC). Like the other audience_* fields, TikTok only returns it for accounts with at least 100 followers.

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.

API Documentation

Platforms

Guides

Endpoints

TikTok

Supported Content Types

Quirks & Gotchas

Privacy Levels & Permalinks

Music & Copyright

Image Format (Photo Mode)

Image sizing (Photo Mode)

The REVIEW Status

Media Limits

Text & Field Limits

Post Options

Posting Options of an Account

Location Tags

Analytics

Profile Analytics

Post Analytics

Quirks

Raw Analytics - Demographics & Audience Data

Account-Level Raw Data

Video-Level Raw Data

​Supported Content Types

​Quirks & Gotchas

​Privacy Levels & Permalinks

​Music & Copyright

​Image Format (Photo Mode)

​Image sizing (Photo Mode)

​The REVIEW Status

​Media Limits

​Text & Field Limits

​Post Options

​Posting Options of an Account

​Location Tags

​Analytics

​Profile Analytics

​Post Analytics

​Quirks

​Raw Analytics - Demographics & Audience Data

​Account-Level Raw Data

​Video-Level Raw Data

Supported Content Types

Quirks & Gotchas

Privacy Levels & Permalinks

Music & Copyright

Image Format (Photo Mode)

Image sizing (Photo Mode)

The REVIEW Status

Media Limits

Text & Field Limits

Post Options

Posting Options of an Account

Location Tags

Analytics

Profile Analytics

Post Analytics

Quirks

Raw Analytics - Demographics & Audience Data

Account-Level Raw Data

Video-Level Raw Data