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

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

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

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

​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

Analytics

Profile Analytics

Post Analytics

Quirks

Raw Analytics - Demographics & Audience Data

Account-Level Raw Data

Video-Level Raw Data