Skip to main content
TikTok for DevelopersTikTok for Developers

Docs

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

Video status overview

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

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

  • The average processing times for video processing vary by video size:
    • 512MB: Less than half a minute
    • 1GB: About one minute
    • 4GB: 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. Indicate 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 for the Upload Video endpoint. 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 endpoint, it indicates that a video has been posted. For the Upload Video endpoint, it indicates that the uploaded video has been posted.
  • 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 video draft to create multiple videos.

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

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

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 for uploading videos for TikTok users to review.

post.publish.complete

publish_id

publish_type

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

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

post.publish.inbox_delivered

publish_id

publish_type

The video has been delivered to the user's inbox of the TikTok mobile app.

publish_type can only be INBOX_SHARE when uploading videos.

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.

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.

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.

publish_cancelled


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