TikTok API - SocialAPI

The TikTok API in SocialAPI connects a TikTok account through TikTok’s authorization screen, using TikTok API for Business. It publishes videos and photo carousels, lists the account’s posts with their counts, reads, replies to, and moderates comments, lists mentions, sends comment.received events, and returns profile counts. A creator connection uses TikTok’s Content Posting API instead, and has no comments or mentions. SocialAPI’s own TikTok app connects the account, so you register nothing: see Platform apps.

At a glance

Field	Value
Platform slug	`tiktok`
Auth	OAuth 2.0 (TikTok authorization screen)
Platform API	TikTok API for Business (Accounts API). TikTok Content Posting API with a creator connection
Status	Available

Capabilities

An unsupported call returns 501 resource.not_supported. This table is for the default connection. A creator connection has its own table.

Feature	Status	Condition
Publish a video	Yes	Public on TikTok. See TikTok publishing
Publish a photo carousel	Yes	2 to 35 images
Send a post to the account’s TikTok drafts	Yes	`post_mode: "inbox"`. Video or photo carousel. The creator finishes the post in the TikTok app
Schedule a post	Yes	`scheduled_at` on the post
First comment on a post	No	`first_comment` is ignored. Comment on the post with Comments after it is published
Update a published post	No	`PATCH /v1/posts/{pid}` returns `409 post.state_invalid` for a published post, and TikTok gives apps no edit call
Delete a published post	No	`DELETE /v1/posts/{pid}` returns HTTP 200 with `results[].outcome: "not_supported"` for the TikTok target, and the post stays live. `POST /v1/posts/{pid}/unpublish` returns `501 resource.not_supported`. Delete the post in the TikTok app
List posts	Yes	Public videos and photo posts with likes, comments, shares, and views. See Sync videos
Live post metrics	Yes	`GET /v1/posts/{pid}/metrics`, for the account’s 20 most recent posts. See Sync videos
Creator info	Yes	Whether the account can post, its longest video, and its interaction locks. See Creator info
Account summary	Yes	Profile and counts. See Account summary
Comments, replies, and comments on a post	Yes	See Comments
Hide and unhide a comment	Conditional	Comments written by other people only
Delete a comment	Conditional	Comments written by the connected account only
Like a comment	Yes
Private reply to a commenter	No	`501 resource.not_supported`
DMs	No	`501 resource.not_supported`
Mentions	Conditional	TikTok Business Accounts only. See Mentions
Reply to a mention	Conditional	Mentions made in a comment only
Reviews	No	TikTok has no reviews. `GET /v1/inbox/reviews/{account_id}` returns `422 account.platform_unsupported`
Automations	No	`422 automation.platform_unsupported`
Analytics export	Partial	Captions and metrics. On the default connection, `include_transcript` or `include_vision` returns `400 account.export_enrichment_not_supported`. A creator connection accepts both
Webhook events	Partial	`comment.received`, `mention.received` when you list mentions, the `post.*` events, `account.connected`, and `account.disconnected`. See Webhook events

The cross-platform matrix is on Platforms.

Connect an account

Connect with POST /v1/accounts/connect and "platform": "tiktok". The shared flow, request fields, and result are in Connect accounts, and the redirect parameters are in Redirect parameters.

curl -X POST https://api.social-api.ai/v1/accounts/connect \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "tiktok",
    "redirect_uri": "https://app.example.com/oauth/callback",
    "state": "session_abc123"
  }'

Response (HTTP 202):

{
  "auth_url": "https://www.tiktok.com/v2/auth/authorize?client_key=...&scope=...&response_type=code&redirect_uri=...&state=4a8f2c1e9b3d7f06a5c2e8b4d1f3a7e2&disable_auto_auth=1",
  "state": "4a8f2c1e9b3d7f06a5c2e8b4d1f3a7e2",
  "message": "Open this link to connect your tiktok account. Once you've authorized, the account will be connected automatically."
}

TikTok-specific rules:

Consent screen. The person always sees TikTok’s consent screen, including when they authorized SocialAPI’s app before.
Account ID. The connected account has an acc_ ID. Its name is the TikTok display name, username is the TikTok handle, and bio is the profile bio. Profile counts are not on the account: read them with Account summary.
Account type. Listing mentions needs a TikTok Business Account: see Mentions.
Connection type. metadata.connection_type is "business" (the default) or "creator": see Creator connection. Without connection_type the connect uses "business". Any other value, including an empty string or a non-string, returns 400 validation.connection_type_invalid.
Reconnect. Reconnect with the same flow: see Reconnect an account.
Accounts connected before 2026-10-13. Comment and mention calls on them return 501 resource.not_supported until you reconnect them.

When TikTok authorization ends

This section covers the default connection. A creator connection is removed when the person removes SocialAPI’s app. The authorization ends when the person removes SocialAPI’s app in TikTok’s settings, or when TikTok refuses to renew it. TikTok sends SocialAPI no notice of a removal, so SocialAPI learns it from the next call that reaches TikTok.

First call. It returns 401 platform.tiktok.auth.
Later calls. They return 403 account.reconnection_required until you reconnect the account.
401 platform.tiktok.unauthorized. TikTok refused one call as unauthorized without saying the authorization is invalid. The account stays usable. Reconnect it if the error repeats.
account.disconnected event. When SocialAPI’s own refresh of the account’s videos meets the ended authorization before one of your calls does, it sends account.disconnected with reconnect_required: true and reason: "posts_sync_auth_failed". A removal in TikTok’s settings does not delete the account from SocialAPI.

Creator connection

A creator connection connects the TikTok account through TikTok’s Content Posting API instead of TikTok API for Business. It works with a personal or creator TikTok account, which does not need to become a TikTok Business Account. Send "connection_type": "creator" in metadata:

curl -X POST https://api.social-api.ai/v1/accounts/connect \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "tiktok",
    "metadata": { "connection_type": "creator" }
  }'

The response has the same shape as in Connect an account, and the connected account’s platform is tiktok.

Feature	Creator connection
Publish a video or photo carousel	Yes. `platform_data.privacy_level` is required on a published video and on a published photo carousel (not on a draft), and must be one of the account’s `privacy_level_options` from Creator info. A missing value returns `400 validation.privacy_level_required`, and a value not listed returns `400 validation.invalid_privacy_level`. When TikTok lists only `SELF_ONLY`, every post is private. When TikTok lists no level, `can_post` is `false` and a post returns `400 validation.posting_limit`. `brand_content_toggle: true` with `SELF_ONLY` returns `400 validation.branded_content_private`
Send a post to the account’s TikTok drafts	Video only. `post_mode: "inbox"`. A photo carousel sent to drafts fails validation on `post_mode`
List posts	Yes. Videos, with likes, comments, shares, and views
Creator info	Yes. `privacy_level_options` lists every level TikTok allows for the account
Account summary	Yes
Analytics export	Yes, including `include_transcript` and `include_vision`
Comments, `comment.received`, and mentions	No. `501 resource.not_supported`

A creator connection asks on TikTok’s consent screen for user.info.basic and user.info.profile, plus the scopes of the permissions you select:

Permission	Scopes
`posts.read`	`video.list`
`posts.write`	`video.publish`, `video.upload`
`analytics.read`	`user.info.stats`

When the person removes SocialAPI’s app in TikTok’s settings, SocialAPI removes the creator connection’s account and sends account.disconnected. Switching connection type. Connecting the same TikTok username with the other connection_type moves the account to that connection type. It keeps its acc_ ID, brand, and history while the account’s authorization on the previous connection type still works. If that authorization no longer works, the connect creates a new account. A reconnect without connection_type uses "business", so send "creator" on every reconnect of a creator connection.

Creator info

GET /v1/accounts/{id}/creator-info returns the settings TikTok applies to the account’s next post. Read it before you publish. It needs the accounts:read scope.

curl https://api.social-api.ai/v1/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/creator-info \
  -H "Authorization: Bearer $SOCAPI_KEY"

Response (HTTP 200):

{
  "platform": "tiktok",
  "nickname": "Acme Corp",
  "avatar_url": "https://p16-sign.tiktokcdn-us.com/avatar.jpeg",
  "can_post": true,
  "max_video_duration_sec": 600,
  "privacy_level_options": ["PUBLIC_TO_EVERYONE"],
  "interaction_settings": {
    "comment_disabled": false,
    "duet_disabled": false,
    "stitch_disabled": false
  }
}

Field	Description
`can_post`	`true` when TikTok lists `PUBLIC_TO_EVERYONE` for the account, `false` when it does not. On a creator connection: `true` when TikTok lists any level
`max_video_duration_sec`	The longest video this account can post, in seconds. Absent when TikTok returns no value
`privacy_level_options`	`["PUBLIC_TO_EVERYONE"]`. Absent when `can_post` is `false`. It never lists another level, because every video publishes publicly. Photo carousels follow a different rule: see TikTok publishing. On a creator connection it lists every level TikTok allows for the account
`interaction_settings`	`true` for a setting the creator turned off in TikTok. A post cannot turn that interaction back on
`avatar_url`	A temporary link from TikTok. Download the image if you need it later

Other platforms return 501 resource.not_supported from this endpoint.

Account summary

GET /v1/platforms/tiktok/accounts/{id}/summary reads the account’s profile and counts from TikTok at the time of the call. It needs the accounts:read scope, and the account needs the analytics.read permission: without it the call returns 403 account.permission_missing.

curl https://api.social-api.ai/v1/platforms/tiktok/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/summary \
  -H "Authorization: Bearer $SOCAPI_KEY"

Response (HTTP 200):

{
  "display_name": "Acme Corp",
  "username": "acmecorp",
  "avatar_url": "https://p16-sign.tiktokcdn-us.com/avatar.jpeg",
  "follower_count": 12400,
  "following_count": 87,
  "likes_count": 980000,
  "video_count": 47,
  "bio_description": "Spring collection out now.",
  "profile_deep_link": "https://www.tiktok.com/@acmecorp",
  "is_verified": false
}

When the account’s authorization lacks a scope for these fields, TikTok refuses the call and SocialAPI returns 403 with the TikTok code in platform.tiktok.<code> (40001, 40118, or 40125). Reconnect the account to grant the scope.

Sync videos

GET /v1/posts?platform=tiktok&account_ids={id} lists the TikTok posts SocialAPI has stored for the account: public videos and photo posts, including posts published outside SocialAPI. Each target carries permalink, media_type (VIDEO or PHOTO), and metrics. SocialAPI refreshes an account’s stored posts on its own, no more than once every 15 minutes. The account needs the posts.read permission. Without it, both sync endpoints return 403 account.permission_missing and SocialAPI refreshes nothing on its own. POST /v1/platforms/tiktok/accounts/{id}/sync refreshes them at once from the 20 most recent posts on TikTok. It needs the accounts:manage scope and has no cooldown. POST /v1/accounts/{id}/sync reads the same 20 posts and allows 1 sync per account every 5 minutes: see Analytics.

curl -X POST https://api.social-api.ai/v1/platforms/tiktok/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/sync \
  -H "Authorization: Bearer $SOCAPI_KEY"

Response (HTTP 200):

{
  "success": true
}

The two endpoints that return counts use different keys for the view count:

Endpoint	Likes, comments, shares	Views
`GET /v1/posts` and `GET /v1/posts/{pid}`	`metrics.likes`, `metrics.comments`, `metrics.shares`. `metrics.saves` is always `0`	`metrics.extra.view_count`. Absent while the count is `0`
`GET /v1/posts/{pid}/metrics`	The same three keys, with `metrics.saves` always `0`	`metrics.views` and `metrics.extra.views`, with the same value. Absent while the count is `0`

TikTok updates likes, comments, shares, and views with a delay of 24 to 48 hours. A call reads TikTok’s latest figures, so a new post shows 0 until TikTok publishes them. Reach, saves, and watch time are not available. GET /v1/posts/{pid}/metrics reads the account’s 20 most recent posts and reuses that read for 10 minutes. For an older post, the target returns 404 resource.not_found. Examples are in TikTok publishing.

Comments

SocialAPI reads, writes, and moderates comments on the account’s own TikTok posts through the shared Comments endpoints. This section holds only what differs on TikTok.

IDs. {postId} is the TikTok video ID, which is the target’s platform_post_id. A comment’s platform_id is {video_id}_{comment_id}, and its id is the sapi_cmt_ ID. Use id or platform_id as {commentId}. Hide, unhide, reply, and list replies need that full form: a bare TikTok comment ID returns 400 validation.comment_id_invalid. Delete and like accept either form.
List. GET /v1/inbox/comments/{postId} returns up to 30 comments per page, and the replies endpoint returns up to 30 replies per page. The list includes hidden comments: is_hidden is true for them. A reply to a hidden comment cannot be listed. Comment text only: images in comments are not returned.
GET /v1/inbox/comments. It lists the account’s posts that have comments, with their comment counts. A read refreshes that list when it is older than 1 hour.
Reply. POST /v1/inbox/comments/{postId} with comment_id replies to that comment. Without comment_id it comments on the post as the connected account. The text holds up to 1,200 characters, and a reply costs 1 interaction credit.
Hide and unhide. For comments written by other people. capabilities.can_hide is false on the connected account’s own comments.
Delete. For comments the connected account wrote. capabilities.can_delete is false on other people’s comments. Hide those instead.
Like. POST and DELETE on /v1/inbox/comments/{postId}/{commentId}/like like and unlike as the connected account. liked_by_viewer is true when the connected account liked the comment.
Private replies. TikTok has none: 501 resource.not_supported, and can_private_reply is false.
Author fields. author_id is TikTok’s unique identifier for the person, author_name is the display name (the handle when TikTok gives none), and author_username is the handle.
Replies. A reply has parent_id set to the platform_id of the comment it answers.

TikTok limits each account to 40 requests per minute for each TikTok call. Beyond that, calls return 429 platform.tiktok.rate_limit.

Mentions

GET /v1/accounts/{id}/mentions lists the public posts that mention the account in the caption and the comments that mention it. TikTok serves mentions for TikTok Business Accounts only. For another account, TikTok refuses the call and SocialAPI returns the TikTok code as platform.tiktok.<code>. The shared endpoints are in Mentions.

Delay. TikTok makes a mention available 24 to 48 hours after it is made, and 24 hours after the account is connected. TikTok asks apps to read each mention list at most once per account per day, after 07:00 UTC.
Page size. A page holds up to 20 mentions, split between caption mentions and comment mentions. Newest first within a page. Follow next_cursor for the rest.
Item fields. author.username is the handle of the person, content.text is the caption or comment text, platform_post_id is the TikTok video ID, and permalink is the video link. metadata is null. A comment mention’s id carries both the video and the comment.
Reply. POST /v1/accounts/{id}/mentions/reply works for a mention made in a comment. Send the mention’s sapi_mnt_ ID as media_id, or send the video ID as media_id with the comment’s platform_id as comment_id. For a mention in a caption, TikTok has no reply: the call returns 400 validation.mention_reply_unsupported. A reply costs 1 interaction credit.
Events. TikTok sends SocialAPI no mention notifications. Each call that returns at least one mention sends a mention.received event: see Mentions you list.

Webhook events

Event	When it fires
`comment.received`	Another person comments on, or replies under, a TikTok post of the account. See `comment.received`
`post.published`, `post.partial`, `post.failed`	A post to this account finished: see Delivery. A TikTok post can finish after the request that created it returned
`account.connected`	You connected a TikTok account
`account.disconnected`	SocialAPI flagged the account for reconnection: see When TikTok authorization ends. On a creator connection, the person removed SocialAPI’s app and SocialAPI removed the account
`account.updated`	The account lost permissions you did not remove yourself (`change` is `permissions_reduced`)

comment.received details on TikTok:

Author. author.id is TikTok’s unique identifier for the person. author.name, author.username, and author.avatar_url come from the comment.
Post. platform_post_id is the TikTok video ID. post_id and permalink are not set.
Not sent. Comments written by the connected account, and TikTok’s deletions and visibility changes. A comment that TikTok no longer lists when SocialAPI reads it, for example one deleted within seconds, produces no event.
Timing. TikTok reports a new comment to SocialAPI within 5 minutes of the comment.
Raw payload. raw_payload holds the TikTok notification.

TikTok has no DM or review events. Listing mentions sends mention.received: see Mentions you list. Every event is described in Webhook events.

Limits

Limit	Value
Video caption	2,200 UTF-16 characters
Photo title (the post `text`)	90 UTF-16 characters
Video file	MP4, MOV, or WebM, 3 seconds to the account’s `max_video_duration_sec`, up to 1 GB
Photo carousel	2 to 35 images, JPEG or WebP, up to 20 MB each
Posts, SocialAPI’s cap	13 per 24 hours and 25 per hour for each account: see Posting velocity caps
Posts, TikTok’s own limit	6 per minute and 15 per day for each account, for the video call and for the photo call. SocialAPI does not enforce the 6 per minute: TikTok refuses a 7th post within a minute
Comment or reply text	1,200 characters
Posts per sync	20
Comments or replies per page	30
Mentions per page	20
TikTok’s request limit	40 requests per minute for each account and each TikTok call. `429 platform.tiktok.rate_limit`. Wait 1 minute, then retry. Credit rules: see when a credit comes back

Scopes

SocialAPI’s TikTok app asks the person for these scopes on TikTok’s consent screen. You apply for no app review. On the default connection, the consent screen is the same whichever permissions you select, and the account is limited to your selection. A creator connection asks for other scopes: see Creator connection.

Scope	Used for
`user.info.basic`	Display name and avatar
`user.info.username`	Handle
`user.info.profile`	Bio, profile link, and verification
`user.info.stats`	Follower, following, likes, and video counts
`user.account.type`	Whether the account is a TikTok Business Account
`user.insights`	TikTok’s daily account insights. No SocialAPI endpoint returns them
`video.list`	List the account’s posts and their counts
`video.insights`	TikTok’s per-post insights, such as watch time. No SocialAPI endpoint returns them
`video.publish`	Publish videos and photo carousels as the account
`video.upload`	Send a post to the account’s TikTok drafts
`comment.list`	Read comments and replies, and receive `comment.received`
`comment.list.manage`	Reply to, hide, like, and delete comments, and reply to comment mentions
`biz.brand.insights`	List mentions

TikTok publishing: fields, media rules, and quirks for publishing
Comments: the shared comment endpoints
Mentions: the shared mention endpoints
Connect accounts: the shared connect flow
Track post delivery: statuses and the publishing state
Platforms: the capability matrix
Errors: every error code

​At a glance

​Capabilities

​Connect an account

​When TikTok authorization ends

​Creator connection

​Creator info

​Account summary

​Sync videos

​Comments

​Mentions

​Webhook events

​Limits

​Scopes

​Related

At a glance

Capabilities

Connect an account

When TikTok authorization ends

Creator connection

Creator info

Account summary

Sync videos

Comments

Mentions

Webhook events

Limits

Scopes

Related