TikTok for Developers

Docs

New: Content Posting API now supports posting photos!

Get Post Status

For content uploaded with the Content Posting API, two mechanisms are provided for developers to check the status of the post by the TikTok user:

  1. Fetch Status endpoint: An API endpoint for polling the status of the post.
  2. Content Posting webhooks: Events that notify your registered endpoint of the final outcome of the post.

Content Status Overview

Content uploaded to TikTok undergoes several stages before it is published. This process can be visualized with the following diagram:

  • Direct Post:
  • Content Upload

The time taken in any given stage can vary by use cases and a time limit is not guaranteed for the content posting process. The following are some helpful details:

  • The average processing times for content processing vary by content size:
    • 512 MB: Less than half a minute
    • 1 GB: About one minute
    • 4 GB: More than two minutes
  • If the post was created for public viewership, it must undergo TikTok's moderation process. Based on TikTok's policies, developers are not provided with the post_id until this process is complete.
    • Moderation usually finishes within one minute.
    • In some cases, moderation may take a few hours.

Fetch Status endpoint

HTTP URL

/v2/post/publish/status/fetch/

HTTP Method

POST

Scope

video.upload/video.publish

Request

Note: Each user access_token is limited to 30 requests per minute.

POST /v2/post/publish/status/fetch/ HTTP /1.1
Host: open.tiktokapis.com
Authorization: Bearer {{AccessToken}}
Content-Type: application/json; charset=UTF-8

{
    "publish_id": {PUBLISH_ID}
}

Response

200 OK

{
    "data": {
        "status": "FAILED",
        "fail_reason": "picture_size_check_failed",
        "publicaly_available_post_id": [],
        "uploaded_bytes": 10000
    },
    
    "error": {
         "code": "ok",
         "message": "",
         "log_id": "202210112248442CB9319E1FB30C1073F3"
     }
}

Nested data struct

Field

Type

Description

status

string


The following are the available statuses:

  • PROCESSING_UPLOAD: Only available for FILE_UPLOAD. Indicates that the upload is in process.
  • PROCESSING_DOWNLOAD: Only available for PULL_FROM_URL. Indicates that the download from the URL is in process.
  • SEND_TO_USER_INBOX: Only available when you choose to upload content. Indicates that a notification has been sent to creator's inbox to complete the draft post using TikTok's editing flow.
  • PUBLISH_COMPLETE: For the Direct Post, it indicates that the content has been posted. For the Upload Content, it indicates that the user has clicked on the inbox notification and has successfully posted the media using TikTok editing flow.
  • FAILED: Indicates that an error has occurred and the entire process has failed.

fail_reason

string

Refer to the fail_reason table to see whether the issue is with the developer, the TikTok creator, or TikTok APIs

publicaly_available_post_id


list<int64>

post_id is returned only if the post is published for public viewership and has been approved by the TikTok moderation process.

Creators may use the uploaded content draft to create multiple pieces of content.

uploaded_bytes

int64

The number of bytes uploaded (1-indexed) for FILE_UPLOAD

downloaded_bytes

int64

The number of bytes downloaded (1-indexed) for PULL_FROM_URL




Nested error struct

HTTP Status

error.code

Description

200

ok

The request was successful

400

invalid_publish_id

The publish_id does not exist

400

token_not_authorized_for_specified_publish_id

The access_token does not have authorization to cancel the publish

401

access_token_invalid

The access_token is invalid or has expired

scope_not_authorized


The access_token does not bear user's grant on video.upload or video.publish

429

rate_limit_exceeded

Your request is blocked due to exceeding the API rate limit

5xx

internal_error

TikTok server or network error. Try again later.

Content Posting webhooks

These events will be sent to your registered server when you have a webhook URL configured for your app in the TikTok for Developers website.

Event Name

Event Values

Description

post.publish.failed

publish_id

reason

publish_type

The publishing action is not successful. The failure reason is sent as an enum string.

publish_type should be INBOX_SHARE when using Upload endpoint (for users to review, edit and post in TikTok once they click inbox notification).

post.publish.complete

publish_id

publish_type

When uploading content, the event indicates that the TikTok user has created a post from the content you sent.

It's possible for the user to make multiple posts from the content associated with one publish_id.

post.publish.inbox_delivered

publish_id

publish_type

Indicates that a notification has been sent to the creator's inbox to complete the draft post using TikTok's editing flow.

publish_type can only be INBOX_SHARE when using upload endpoints.

post.publish.publicaly_available

publish_id

post_id

publish_type

This event is sent when a post associated with the publish_id has become publicly viewable on TikTok. Non-public posts will not trigger this event unless the user makes them public later.

post.publish.no_longer_publicaly_available

publish_id

post_id

publish_type

The event is sent when a post associated with the publish_id has ceased to be publicly viewable.

Fail reasons

The following is a list of fail_reason that may be returned by the HTTP endpoint or webhook events.

fail_reason

Guidance

file_format_check_failed

Unsupported media format. See Video Restrictions and Photo Restrictions.

duration_check_failed

Video does not meet our duration restrictions. See Video Restrictions.

frame_rate_check_failed

Unsupported frame rate. See Video Restrictions.

picture_size_check_failed

Upsupported picture size. See Video Restrictions and Photo Restrictions.

internal

Some parts of the TikTok server may currently be unavailable. This is a retryable error.

video_pull_failed


The TikTok server encountered a connection error while downloading the specified video resource, or the download is terminated since it can not be completed within the one-hour timeout.


Check if the supplied URL is publicly accessible or bandwidth-limited. If developers are certain that the URL is valid, a retry is recommended.

photo_pull_failed


The TikTok server encountered a connection error while downloading the specified photo resource, or the download is terminated since it can not be completed within the one-hour timeout.


Check if the supplied URL is publicly accessible or bandwidth-limited. If developers are certain that the URL is valid, a retry is recommended.

publish_cancelled


Developers can cancel an ongoing download. After a successful cancellation, developers will receive a webhook containing this error reason.