> ## Documentation Index
> Fetch the complete documentation index at: https://docs.social-api.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Base URL: https://api.social-api.ai/v1. Send your API key in the Authorization header: Authorization: Bearer <your API key>.
> Every error response from /v1 is JSON: { "error": { "code", "message", "meta" (optional) }, "request_id" }. Branch on error.code; use error.message only for logs.
> A 429 response carries a Retry-After header, in seconds, when the limit has a known wait.
> Paginated list endpoints return next_cursor, at the top level or inside pagination (see /guides/pagination). Pass it as the cursor query parameter to get the next page. An absent or empty next_cursor means you have the last page.
> Treat every ID as an opaque string: do not parse it or assume a format.
> Support differs by platform and by operation. Check /platforms/overview before assuming an operation works on a platform. An unsupported operation returns 501 with error.code resource.not_supported.

# TikTok API

> Connect TikTok accounts to publish videos and photo carousels, read and moderate comments, list mentions, and read profile counts and post metrics.

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](#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](/guides/platform-credentials).

## 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](#creator-connection) |
| Status | Available |

## Capabilities

An unsupported call returns `501 resource.not_supported`. This table is for the default connection. A [creator connection](#creator-connection) has its own table.

| Feature | Status | Condition |
| - | - | - |
| Publish a video | Yes | Public on TikTok. See [TikTok publishing](/platforms/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](#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](#sync-videos) |
| Live post metrics | Yes | `GET /v1/posts/{pid}/metrics`, for the account's 20 most recent posts. See [Sync videos](#sync-videos) |
| Creator info | Yes | Whether the account can post, its longest video, and its interaction locks. See [Creator info](#creator-info) |
| Account summary | Yes | Profile and counts. See [Account summary](#account-summary) |
| Comments, replies, and comments on a post | Yes | See [Comments](#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](#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](#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](#webhook-events) |

The cross-platform matrix is on [Platforms](/platforms/overview).

## Connect an account

Connect with `POST /v1/accounts/connect` and `"platform": "tiktok"`. The shared flow, request fields, and result are in [Connect accounts](/guides/connect-accounts), and the redirect parameters are in [Redirect parameters](/guides/connect-accounts#redirect-parameters).

```bash theme={null}
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):

```json theme={null}
{
  "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-summary).
* **Account type.** Listing mentions needs a TikTok Business Account: see [Mentions](#mentions).
* **Connection type.** `metadata.connection_type` is `"business"` (the default) or `"creator"`: see [Creator connection](#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](/guides/connect-accounts#reconnect-an-account).
* **Accounts connected before 2026-10-13.** [Comment](#comments) and [mention](#mentions) 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](#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`:

```bash theme={null}
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](#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](#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](/guides/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.

```bash theme={null}
curl https://api.social-api.ai/v1/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/creator-info \
  -H "Authorization: Bearer $SOCAPI_KEY"
```

Response (HTTP 200):

```json theme={null}
{
  "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](#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](/platforms/tiktok/publishing#privacy-level-differs-for-videos-and-photos). On a [creator connection](#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](/guides/permissions): without it the call returns `403 account.permission_missing`.

```bash theme={null}
curl https://api.social-api.ai/v1/platforms/tiktok/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/summary \
  -H "Authorization: Bearer $SOCAPI_KEY"
```

Response (HTTP 200):

```json theme={null}
{
  "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](/guides/permissions). 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](/guides/analytics#refresh-an-accounts-posts).

```bash theme={null}
curl -X POST https://api.social-api.ai/v1/platforms/tiktok/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/sync \
  -H "Authorization: Bearer $SOCAPI_KEY"
```

Response (HTTP 200):

```json theme={null}
{
  "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](/platforms/tiktok/publishing#6-retrieve-posts).

## Comments

SocialAPI reads, writes, and moderates comments on the account's own TikTok posts through the shared [Comments](/guides/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](/guides/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](/guides/webhook-events#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`](/guides/webhook-events#comment-received) |
| `post.published`, `post.partial`, `post.failed` | A post to this account finished: see [Delivery](/guides/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](#when-tiktok-authorization-ends). On a [creator connection](#creator-connection), the person removed SocialAPI's app and SocialAPI removed the account |
| `account.updated` | The account lost [permissions](/guides/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](/guides/webhook-events#mentions-you-list). Every event is described in [Webhook events](/guides/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](/guides/rate-limits#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](/guides/plans#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](/guides/permissions) you select, and the account is limited to your selection. A creator connection asks for other scopes: see [Creator connection](#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 |

## Related

* [TikTok publishing](/platforms/tiktok/publishing): fields, media rules, and quirks for publishing
* [Comments](/guides/comments): the shared comment endpoints
* [Mentions](/guides/mentions): the shared mention endpoints
* [Connect accounts](/guides/connect-accounts): the shared connect flow
* [Track post delivery](/guides/delivery): statuses and the `publishing` state
* [Platforms](/platforms/overview): the capability matrix
* [Errors](/guides/errors): every error code


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.