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:
- Fetch Status endpoint: An API endpoint for polling the status of the post.
- 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:
|
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> |
Creators may use the uploaded content draft to create multiple pieces of content. |
uploaded_bytes | int64 | The number of bytes uploaded (1-indexed) for |
downloaded_bytes | int64 | The number of bytes downloaded (1-indexed) for |
Nested error struct
HTTP Status | error.code | Description |
200 | ok | The request was successful |
400 | invalid_publish_id | The |
400 | token_not_authorized_for_specified_publish_id | The |
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 | |
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.
|
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 |
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.
|
post.publish.publicaly_available | publish_id post_id publish_type | This event is sent when a post associated with the |
post.publish.no_longer_publicaly_available | publish_id post_id publish_type | The event is sent when a post associated with the |
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. |