Skip to content

TikTok Post Search API (V1) ​

GET
API health status
Healthy Available Limited Mostly unavailable No data
Loading health status...

Searches TikTok posts by keyword with offset pagination plus sorting, publish-time, and region controls. Use it to support regional content discovery, topic research, or monitoring keyword-related videos.

Parameters ​

NameInTypeRequiredDefaultDescription
tokenquerystringYes-Security token for API access.
keywordquerystringYes-Search keywords.
offsetqueryintegerNo0Pagination offset, starting from 0 and stepping by 20.
sortTypequerystringNoRELEVANCESorting criteria for search results.


Available Values:

- RELEVANCE: Relevance (Default)

- MOST_LIKED: Most Liked
publishTimequerystringNoALLFilter posts by publishing time.


Available Values:

- ALL: All Time

- ONE_DAY: Last 24 Hours

- ONE_WEEK: Last 7 Days

- ONE_MONTH: Last 30 Days

- THREE_MONTHS: Last 90 Days

- HALF_YEAR: Last 180 Days
regionquerystringNoUSISO 3166-1 alpha-2 country code (e.g., 'US', 'GB').

Code Samples ​

bash
curl --max-time 120 -X GET 'https://api.justoneapi.com/api/tiktok/search-post/v1?token=YOUR_API_KEY&keyword=VALUE'
text
I want to use the "Post Search (V1)" API from JustOneAPI.
Base URL: https://api.justoneapi.com.
API Path: /api/tiktok/search-post/v1?token=YOUR_API_KEY&keyword=VALUE
API Endpoint: BASE_URL + /api/tiktok/search-post/v1?token=YOUR_API_KEY&keyword=VALUE
HTTP Method: GET
Authentication: Append the "token" query parameter to the URL.
OpenAPI Definition: https://docs.justoneapi.com/openapi/tiktok/post-search-v1-en.json

Parameters:
- token (query): Security token for API access. (Required)
- keyword (query): Search keywords. (Required)
- offset (query): Pagination offset, starting from 0 and stepping by 20.
- sortType (query): Sorting criteria for search results.

Available Values:
- `RELEVANCE`: Relevance (Default)
- `MOST_LIKED`: Most Liked
- publishTime (query): Filter posts by publishing time.

Available Values:
- `ALL`: All Time
- `ONE_DAY`: Last 24 Hours
- `ONE_WEEK`: Last 7 Days
- `ONE_MONTH`: Last 30 Days
- `THREE_MONTHS`: Last 90 Days
- `HALF_YEAR`: Last 180 Days
- region (query): ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB').

Return format: safely handle JSON or text according to the actual Content-Type.

Response Handling & Error Codes:
1. Business results should be determined by the "code" field in the response body (code 0 means success).
2. Timeout Recommendation: Set the request timeout to 120 seconds. If 120 seconds is too long for your use case, use at least 60 seconds, but a small number of requests may time out before receiving a result.
3. Business Code Reference:
   - 0: Success
   - 100: Invalid or Inactive Token
   - 301: Collection Failed. Please Retry.
   - 302: Rate Limit Exceeded
   - 303: Daily Quota Exceeded
   - 400: Invalid Parameters
   - 500: Internal Server Error
   - 600: Permission Denied
   - 601: Insufficient Balance
   - 602: Token Budget Exceeded
4. Code 601 means the shared account balance is insufficient. Code 602 means the current API token's own cumulative budget limit has been reached. Token budget limits do not transfer funds out of the shared account balance.

Please help me write a script in my preferred programming language to call this API and handle the response.
python
import requests

BASE_URL = "https://api.justoneapi.com"  # Provided by OpenAPI servers

url = BASE_URL + "/api/tiktok/search-post/v1?token=YOUR_API_KEY&keyword=VALUE"
response = requests.get(url, timeout=120)
print(response.status_code)
if response.content:
    content_type = response.headers.get("content-type", "").lower()
    if "json" in content_type:
        try:
            print(response.json())
        except ValueError:
            print(response.text)
    elif content_type.startswith("text/") or "xml" in content_type or content_type.split(";", 1)[0].strip() in {"application/javascript", "application/x-www-form-urlencoded", "application/graphql"}:
        print(response.text)
    else:
        with open("response.bin", "wb") as output:
            output.write(response.content)
        print(f"Saved {len(response.content)} bytes to response.bin")
js
const BASE_URL = "https://api.justoneapi.com"; // Provided by OpenAPI servers
const url = BASE_URL + "/api/tiktok/search-post/v1?token=YOUR_API_KEY&keyword=VALUE";

const response = await fetch(url, {
  method: "GET",
  signal: AbortSignal.timeout(120000)
});
console.log(response.status);
const responseBytes = await response.arrayBuffer();
if (responseBytes.byteLength) {
  const contentType = (response.headers.get("content-type") || "").toLowerCase();
  const mediaType = contentType.split(";", 1)[0].trim();
  const textual = contentType.startsWith("text/") || contentType.includes("json") || contentType.includes("xml") || ["application/javascript", "application/x-www-form-urlencoded", "application/graphql"].includes(mediaType);
  if (textual) {
    const responseText = new TextDecoder().decode(responseBytes);
    let data = responseText;
    if (contentType.includes("json")) {
      try { data = JSON.parse(responseText); } catch { /* Keep the raw body. */ }
    }
    console.log(data);
  } else {
    console.log(`Received ${responseBytes.byteLength} binary bytes`);
  }
}
java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;

public class Main {
    public static void main(String[] args) throws Exception {
        final String BASE_URL = "https://api.justoneapi.com"; // Provided by OpenAPI servers
        final String url = BASE_URL + "/api/tiktok/search-post/v1?token=YOUR_API_KEY&keyword=VALUE";

        HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(120)).build();
        HttpRequest.Builder builder = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .timeout(Duration.ofSeconds(120))
            .method("GET", HttpRequest.BodyPublishers.noBody());

        HttpRequest request = builder.build();

        HttpResponse<byte[]> response = client.send(request, HttpResponse.BodyHandlers.ofByteArray());
        System.out.println(response.statusCode());
        String contentType = response.headers().firstValue("content-type").orElse("").toLowerCase();
        String mediaType = contentType.split(";", 2)[0].trim();
        if (contentType.startsWith("text/") || contentType.contains("json") || contentType.contains("xml") || mediaType.equals("application/javascript") || mediaType.equals("application/x-www-form-urlencoded") || mediaType.equals("application/graphql")) {
            System.out.println(new String(response.body(), StandardCharsets.UTF_8));
        } else {
            Files.write(Path.of("response.bin"), response.body());
            System.out.println("Saved " + response.body().length + " bytes to response.bin");
        }
    }
}
go
package main

import (
	"fmt"
	"io"
	"os"
	"strings"
	"net/http"
	"time"
)

const BASE_URL = "https://api.justoneapi.com" // Provided by OpenAPI servers

func main() {
	client := &http.Client{Timeout: 120 * time.Second}
	url := BASE_URL + "/api/tiktok/search-post/v1?token=YOUR_API_KEY&keyword=VALUE"
	req, _ := http.NewRequest("GET", url, nil)
	resp, _ := client.Do(req)
	defer resp.Body.Close()
	fmt.Println(resp.StatusCode)
	bodyBytes, _ := io.ReadAll(resp.Body)
	contentType := strings.ToLower(resp.Header.Get("Content-Type"))
	mediaType := strings.TrimSpace(strings.SplitN(contentType, ";", 2)[0])
	if strings.HasPrefix(contentType, "text/") || strings.Contains(contentType, "json") || strings.Contains(contentType, "xml") || mediaType == "application/javascript" || mediaType == "application/x-www-form-urlencoded" || mediaType == "application/graphql" {
		fmt.Println(string(bodyBytes))
	} else {
		os.WriteFile("response.bin", bodyBytes, 0600)
		fmt.Printf("Saved %d bytes to response.bin\n", len(bodyBytes))
	}
}
php
<?php
$BASE_URL = 'https://api.justoneapi.com'; // Provided by OpenAPI servers
$url = $BASE_URL . '/api/tiktok/search-post/v1?token=YOUR_API_KEY&keyword=VALUE';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 120);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$contentType = strtolower((string) curl_getinfo($ch, CURLINFO_CONTENT_TYPE));
curl_close($ch);
echo $status . PHP_EOL;
$mediaType = trim(explode(';', $contentType, 2)[0]);
if (str_starts_with($contentType, 'text/') || str_contains($contentType, 'json') || str_contains($contentType, 'xml') || in_array($mediaType, ['application/javascript', 'application/x-www-form-urlencoded', 'application/graphql'], true)) {
    echo $response;
} else {
    file_put_contents('response.bin', $response);
    echo 'Saved ' . strlen($response) . ' bytes to response.bin' . PHP_EOL;
}

Response Fields ​

Key fields in a successful response (code = 0).

Search results and pagination6 fields

data

One page of TikTok post search results and pagination information.

FieldTypeDescription
status_codeintegerNumeric status reported by TikTok for the search response.
has_moreintegerPagination flag. A value of 1 indicates more results are available, and 0 indicates the end of the results.
cursorintegerPagination cursor. If has_more indicates more results, pass this cursor as offset in the next request.
aweme_listarray | nullAdditional post list returned by TikTok. This field can be empty or null. Search entries are available in search_item_list.
search_item_listarray | nullSearch entries on the current page. This field can be null at the end. Posts can recur between pages. Use each entry's aweme_info.aweme_id to deduplicate them.
search_item_list[]objectOne search result entry.
Post content23 fields

data.search_item_list[].aweme_info

Post data for the search entry, including content, author, and available media metadata.

FieldTypeDescription
aweme_idstringTikTok post ID represented as text.
aweme_typeintegerNumeric post type code reported by TikTok.
author_user_idintegerNumeric TikTok author ID. For exact IDs in JavaScript use the text field author.uid.
create_timeintegerPost publication time as a Unix timestamp in seconds.
descstringPost caption supplied by TikTok.
desc_languagestringLanguage code reported for the post caption.
content_descstringAdditional description text supplied for the post.
search_descstringDescription text returned for display in search results.
share_urlstringShare URL for the post.
regionstringRegion code returned for the post.
group_idstringContent group identifier represented as text.
is_adsbooleanWhether TikTok marks the post as advertising.
is_paid_contentbooleanWhether TikTok marks the post as paid content.
is_close_friends_onlybooleanWhether the post is marked for close friends only.
is_topintegerNumeric pinned-post flag returned for this post.
is_vrbooleanWhether the post is marked as VR content.
has_danmakubooleanWhether the post is marked as having a danmaku overlay.
is_description_translatablebooleanWhether TikTok marks the description as translatable.
is_text_sticker_translatablebooleanWhether TikTok marks the text stickers as translatable.
is_title_translatablebooleanWhether TikTok marks the title as translatable.
prevent_downloadbooleanWhether download prevention is marked for the post.
music_begin_time_in_msintegerMusic start position for the post in milliseconds.
no_selected_musicbooleanWhether TikTok indicates the post has no selected music.
Author15 fields

data.search_item_list[].aweme_info.author

TikTok account that published the post.

FieldTypeDescription
uidstringTikTok author ID represented as text. Use this field to preserve exact digits.
unique_idstringPublic TikTok username or handle.
nicknamestringAuthor display name.
short_idstringShort identifier field returned for the author.
custom_verifystringCustom verification label returned for the account.
enterprise_verify_reasonstringBusiness verification text returned for the account.
verification_typeintegerNumeric verification code returned for the account.
follower_countintegerFollower count reported for the author.
following_countintegerNumber of accounts the author follows.
total_favoritedintegerLike total reported for the author's posts.
aweme_countintegerPost count reported for the author.
with_commerce_entrybooleanWhether a commerce entry is marked for the account.
with_shop_entrybooleanWhether a shop entry is marked for the account.
search_user_descstringDescription text returned for the author in search results.
search_user_namestringName text returned for the author in search results.
Author avatars35 fields

data.search_item_list[].aweme_info.author

FieldTypeDescription
avatar_168x168objectAuthor avatar in the 168x168 representation.
avatar_168x168.uristringMedia identifier or URI supplied by TikTok.
avatar_168x168.url_listarrayMedia URLs returned for this representation.
avatar_168x168.url_list[]stringOne media URL for this representation.
avatar_168x168.widthintegerMedia width in pixels when reported.
avatar_168x168.heightintegerMedia height in pixels when reported.
avatar_168x168.data_sizeintegerData size value reported for this representation.
avatar_300x300objectAuthor avatar in the 300x300 representation.
avatar_300x300.uristringMedia identifier or URI supplied by TikTok.
avatar_300x300.url_listarrayMedia URLs returned for this representation.
avatar_300x300.url_list[]stringOne media URL for this representation.
avatar_300x300.widthintegerMedia width in pixels when reported.
avatar_300x300.heightintegerMedia height in pixels when reported.
avatar_300x300.data_sizeintegerData size value reported for this representation.
avatar_largerobjectLarger author avatar representation.
avatar_larger.uristringMedia identifier or URI supplied by TikTok.
avatar_larger.url_listarrayMedia URLs returned for this representation.
avatar_larger.url_list[]stringOne media URL for this representation.
avatar_larger.widthintegerMedia width in pixels when reported.
avatar_larger.heightintegerMedia height in pixels when reported.
avatar_larger.data_sizeintegerData size value reported for this representation.
avatar_mediumobjectMedium author avatar representation.
avatar_medium.uristringMedia identifier or URI supplied by TikTok.
avatar_medium.url_listarrayMedia URLs returned for this representation.
avatar_medium.url_list[]stringOne media URL for this representation.
avatar_medium.widthintegerMedia width in pixels when reported.
avatar_medium.heightintegerMedia height in pixels when reported.
avatar_medium.data_sizeintegerData size value reported for this representation.
avatar_thumbobjectThumbnail author avatar representation.
avatar_thumb.uristringMedia identifier or URI supplied by TikTok.
avatar_thumb.url_listarrayMedia URLs returned for this representation.
avatar_thumb.url_list[]stringOne media URL for this representation.
avatar_thumb.widthintegerMedia width in pixels when reported.
avatar_thumb.heightintegerMedia height in pixels when reported.
avatar_thumb.data_sizeintegerData size value reported for this representation.
Engagement10 fields

data.search_item_list[].aweme_info.statistics

Engagement metrics returned for the post.

FieldTypeDescription
aweme_idstringTikTok post ID for these statistics, represented as text.
play_countintegerView or play count reported for the post.
digg_countintegerLike count reported for the post.
comment_countintegerComment count reported for the post.
share_countintegerShare count reported for the post.
collect_countintegerSave count reported for the post.
download_countintegerDownload count reported for the post.
repost_countintegerRepost count reported for the post.
forward_countintegerForward count reported separately for the post.
whatsapp_share_countintegerShare count reported for WhatsApp.
Video and covers41 fields

data.search_item_list[].aweme_info.video

Video metadata and media representations, when supplied.

FieldTypeDescription
durationintegerVideo duration in milliseconds.
widthintegerVideo width in pixels.
heightintegerVideo height in pixels.
ratiostringVideo resolution or ratio label returned by TikTok.
has_watermarkbooleanWhether the video is marked as having a watermark.
cover_is_custombooleanWhether the video is marked as using a custom cover.
big_thumbsarrayThumbnail sprite metadata for the video, when available.
big_thumbs[]objectOne thumbnail sprite entry.
big_thumbs[].img_numintegerNumber of thumbnails reported for the sprite entry.
big_thumbs[].img_urlstringURL for the thumbnail sprite.
big_thumbs[].img_x_lenintegerNumber of thumbnail columns reported for the sprite.
big_thumbs[].img_y_lenintegerNumber of thumbnail rows reported for the sprite.
big_thumbs[].img_x_sizeintegerWidth of one thumbnail in pixels.
big_thumbs[].img_y_sizeintegerHeight of one thumbnail in pixels.
big_thumbs[].img_urlsarrayThumbnail sprite URLs returned for this entry.
big_thumbs[].img_urls[]stringOne thumbnail sprite URL.
coverobjectVideo cover image.
cover.uristringMedia identifier or URI supplied by TikTok.
cover.url_listarrayMedia URLs returned for this representation.
cover.url_list[]stringOne media URL for this representation.
cover.widthintegerMedia width in pixels when reported.
cover.heightintegerMedia height in pixels when reported.
cover.data_sizeintegerData size value reported for this representation.
origin_coverobjectOriginal cover representation returned for the video.
origin_cover.uristringMedia identifier or URI supplied by TikTok.
origin_cover.url_listarrayMedia URLs returned for this representation.
origin_cover.url_list[]stringOne media URL for this representation.
origin_cover.widthintegerMedia width in pixels when reported.
origin_cover.heightintegerMedia height in pixels when reported.
origin_cover.data_sizeintegerData size value reported for this representation.
dynamic_coverobjectDynamic cover representation for the video.
dynamic_cover.uristringMedia identifier or URI supplied by TikTok.
dynamic_cover.url_listarrayMedia URLs returned for this representation.
dynamic_cover.url_list[]stringOne media URL for this representation.
dynamic_cover.widthintegerMedia width in pixels when reported.
dynamic_cover.heightintegerMedia height in pixels when reported.
dynamic_cover.data_sizeintegerData size value reported for this representation.
animated_coverobjectAnimated cover representation for the video.
animated_cover.uristringMedia identifier or URI supplied by TikTok.
animated_cover.url_listarrayMedia URLs returned for this representation.
animated_cover.url_list[]stringOne media URL for this representation.
Playback and download addresses50 fields

data.search_item_list[].aweme_info.video

FieldTypeDescription
bit_ratearrayAvailable video playback variants and associated encoding metadata.
bit_rate[]objectOne video playback variant.
bit_rate[].bit_rateintegerBitrate reported for the playback variant.
bit_rate[].fpsintegerFrames per second reported for the playback variant.
bit_rate[].gear_namestringQuality tier label for the playback variant.
bit_rate[].quality_typeintegerNumeric quality code reported for the playback variant.
bit_rate[].HDR_typestringHDR type label reported for the playback variant.
bit_rate[].HDR_bitstringHDR bit-depth label returned for the playback variant.
bit_rate[].play_addrobjectPlayback address metadata for this variant.
bit_rate[].play_addr.uristringMedia identifier or URI supplied by TikTok.
bit_rate[].play_addr.url_listarrayMedia URLs returned for this representation.
bit_rate[].play_addr.url_list[]stringOne media URL for this representation.
bit_rate[].play_addr.widthintegerMedia width in pixels when reported.
bit_rate[].play_addr.heightintegerMedia height in pixels when reported.
bit_rate[].play_addr.data_sizeintegerData size value reported for this representation.
play_addrobjectPlayback media representation for the video.
play_addr.uristringMedia identifier or URI supplied by TikTok.
play_addr.url_listarrayMedia URLs returned for this representation.
play_addr.url_list[]stringOne media URL for this representation.
play_addr.widthintegerMedia width in pixels when reported.
play_addr.heightintegerMedia height in pixels when reported.
play_addr.data_sizeintegerData size value reported for this representation.
play_addr_h264objectH.264 playback media representation.
play_addr_h264.uristringMedia identifier or URI supplied by TikTok.
play_addr_h264.url_listarrayMedia URLs returned for this representation.
play_addr_h264.url_list[]stringOne media URL for this representation.
play_addr_h264.widthintegerMedia width in pixels when reported.
play_addr_h264.heightintegerMedia height in pixels when reported.
play_addr_h264.data_sizeintegerData size value reported for this representation.
play_addr_bytevc1objectByteVC1 playback media representation.
play_addr_bytevc1.uristringMedia identifier or URI supplied by TikTok.
play_addr_bytevc1.url_listarrayMedia URLs returned for this representation.
play_addr_bytevc1.url_list[]stringOne media URL for this representation.
play_addr_bytevc1.widthintegerMedia width in pixels when reported.
play_addr_bytevc1.heightintegerMedia height in pixels when reported.
play_addr_bytevc1.data_sizeintegerData size value reported for this representation.
download_addrobjectDownload media representation supplied for the video.
download_addr.uristringMedia identifier or URI supplied by TikTok.
download_addr.url_listarrayMedia URLs returned for this representation.
download_addr.url_list[]stringOne media URL for this representation.
download_addr.widthintegerMedia width in pixels when reported.
download_addr.heightintegerMedia height in pixels when reported.
download_addr.data_sizeintegerData size value reported for this representation.
download_no_watermark_addrobjectDownload representation identified as watermark-free.
download_no_watermark_addr.uristringMedia identifier or URI supplied by TikTok.
download_no_watermark_addr.url_listarrayMedia URLs returned for this representation.
download_no_watermark_addr.url_list[]stringOne media URL for this representation.
download_no_watermark_addr.widthintegerMedia width in pixels when reported.
download_no_watermark_addr.heightintegerMedia height in pixels when reported.
download_no_watermark_addr.data_sizeintegerData size value reported for this representation.
Music details48 fields

data.search_item_list[].aweme_info.music

Music or sound metadata associated with the post.

FieldTypeDescription
idintegerNumeric music or sound ID. Use id_str for exact digits in JavaScript.
id_strstringMusic or sound ID represented as text.
midstringMusic identifier field returned as text.
titlestringMusic or sound title.
authorstringDisplay name for the music or sound author.
albumstringAlbum name returned for the track.
durationintegerMusic or sound duration in seconds.
audition_durationintegerPreview duration reported for the music.
shoot_durationintegerRecording duration reported for use of the music.
video_durationintegerVideo duration value supplied in the music metadata.
create_timeintegerMusic or sound creation time as a Unix timestamp in seconds when supplied.
user_countintegerNumber of users reported for use of the music.
languagestringLanguage code returned for the music.
owner_idstringSound owner's TikTok user ID represented as text.
owner_handlestringSound owner's public TikTok username.
owner_nicknamestringDisplay name of the sound owner.
is_original_soundbooleanWhether the item is marked as an original sound.
is_commerce_musicbooleanWhether the music is marked as commercial music.
is_author_artistbooleanWhether the music author is marked as an artist.
can_not_reusebooleanWhether the sound is marked as unavailable for reuse.
has_human_voicebooleanWhether this sound is marked as containing a human voice.
duration_high_precisionobjectHigher-precision duration figures returned for the music.
duration_high_precision.duration_precisionnumberHigher-precision duration value for the sound.
duration_high_precision.audition_duration_precisionnumberHigher-precision preview duration value.
duration_high_precision.shoot_duration_precisionnumberHigher-precision recording duration value.
duration_high_precision.video_duration_precisionnumberHigher-precision video duration value in the music metadata.
matched_songobjectMatched song details for the sound, when supplied.
matched_song.idstringMatched song ID represented as text.
matched_song.titlestringMatched song title.
matched_song.authorstringMatched song author display name.
matched_song.full_durationintegerFull duration value reported for the matched song.
matched_song.cover_mediumobjectCover representation for the matched song.
matched_song.cover_medium.uristringMedia identifier or URI supplied by TikTok.
matched_song.cover_medium.url_listarrayMedia URLs returned for this representation.
matched_song.cover_medium.url_list[]stringOne media URL for this representation.
matched_song.cover_medium.widthintegerMedia width in pixels when reported.
matched_song.cover_medium.heightintegerMedia height in pixels when reported.
matched_pgc_soundobjectMatched published sound details, when supplied.
matched_pgc_sound.titlestringMatched published sound title.
matched_pgc_sound.authorstringMatched published sound author display name.
matched_pgc_sound.cover_mediumobjectCover representation for the matched published sound.
matched_pgc_sound.cover_medium.uristringMedia identifier or URI supplied by TikTok.
matched_pgc_sound.cover_medium.url_listarrayMedia URLs returned for this representation.
matched_pgc_sound.cover_medium.url_list[]stringOne media URL for this representation.
matched_pgc_sound.cover_medium.widthintegerMedia width in pixels when reported.
matched_pgc_sound.cover_medium.heightintegerMedia height in pixels when reported.
music_release_infoobjectRelease metadata associated with the track.
music_release_info.is_new_release_songbooleanWhether the song is marked as a new release.
Music artists and media38 fields

data.search_item_list[].aweme_info.music

FieldTypeDescription
artistsarrayArtists associated with the music, when available.
artists[]objectOne artist associated with the music.
artists[].uidstringTikTok artist account ID represented as text.
artists[].handlestringPublic TikTok username of the artist.
artists[].nick_namestringArtist display name.
artists[].is_verifiedbooleanWhether the artist account is marked as verified.
artists[].avatarobjectAvatar representation for the artist.
artists[].avatar.uristringMedia identifier or URI supplied by TikTok.
artists[].avatar.url_listarrayMedia URLs returned for this representation.
artists[].avatar.url_list[]stringOne media URL for this representation.
play_urlobjectPlayback representation for the sound.
play_url.uristringMedia identifier or URI supplied by TikTok.
play_url.url_listarrayMedia URLs returned for this representation.
play_url.url_list[]stringOne media URL for this representation.
play_url.widthintegerMedia width in pixels when reported.
play_url.heightintegerMedia height in pixels when reported.
play_url.data_sizeintegerData size value reported for this representation.
cover_largeobjectLarge music cover representation.
cover_large.uristringMedia identifier or URI supplied by TikTok.
cover_large.url_listarrayMedia URLs returned for this representation.
cover_large.url_list[]stringOne media URL for this representation.
cover_large.widthintegerMedia width in pixels when reported.
cover_large.heightintegerMedia height in pixels when reported.
cover_large.data_sizeintegerData size value reported for this representation.
cover_mediumobjectMedium music cover representation.
cover_medium.uristringMedia identifier or URI supplied by TikTok.
cover_medium.url_listarrayMedia URLs returned for this representation.
cover_medium.url_list[]stringOne media URL for this representation.
cover_medium.widthintegerMedia width in pixels when reported.
cover_medium.heightintegerMedia height in pixels when reported.
cover_medium.data_sizeintegerData size value reported for this representation.
cover_thumbobjectThumbnail music cover representation.
cover_thumb.uristringMedia identifier or URI supplied by TikTok.
cover_thumb.url_listarrayMedia URLs returned for this representation.
cover_thumb.url_list[]stringOne media URL for this representation.
cover_thumb.widthintegerMedia width in pixels when reported.
cover_thumb.heightintegerMedia height in pixels when reported.
cover_thumb.data_sizeintegerData size value reported for this representation.
Added sound details48 fields

data.search_item_list[].aweme_info.added_sound_music_info

Metadata for an added sound, when supplied.

FieldTypeDescription
idintegerNumeric music or sound ID. Use id_str for exact digits in JavaScript.
id_strstringMusic or sound ID represented as text.
midstringMusic identifier field returned as text.
titlestringMusic or sound title.
authorstringDisplay name for the music or sound author.
albumstringAlbum name returned for the track.
durationintegerMusic or sound duration in seconds.
audition_durationintegerPreview duration reported for the music.
shoot_durationintegerRecording duration reported for use of the music.
video_durationintegerVideo duration value supplied in the music metadata.
create_timeintegerMusic or sound creation time as a Unix timestamp in seconds when supplied.
user_countintegerNumber of users reported for use of the music.
languagestringLanguage code returned for the music.
owner_idstringSound owner's TikTok user ID represented as text.
owner_handlestringSound owner's public TikTok username.
owner_nicknamestringDisplay name of the sound owner.
is_original_soundbooleanWhether the item is marked as an original sound.
is_commerce_musicbooleanWhether the music is marked as commercial music.
is_author_artistbooleanWhether the music author is marked as an artist.
can_not_reusebooleanWhether the sound is marked as unavailable for reuse.
has_human_voicebooleanWhether this sound is marked as containing a human voice.
duration_high_precisionobjectHigher-precision duration figures returned for the music.
duration_high_precision.duration_precisionnumberHigher-precision duration value for the sound.
duration_high_precision.audition_duration_precisionnumberHigher-precision preview duration value.
duration_high_precision.shoot_duration_precisionnumberHigher-precision recording duration value.
duration_high_precision.video_duration_precisionnumberHigher-precision video duration value in the music metadata.
matched_songobjectMatched song details for the sound, when supplied.
matched_song.idstringMatched song ID represented as text.
matched_song.titlestringMatched song title.
matched_song.authorstringMatched song author display name.
matched_song.full_durationintegerFull duration value reported for the matched song.
matched_song.cover_mediumobjectCover representation for the matched song.
matched_song.cover_medium.uristringMedia identifier or URI supplied by TikTok.
matched_song.cover_medium.url_listarrayMedia URLs returned for this representation.
matched_song.cover_medium.url_list[]stringOne media URL for this representation.
matched_song.cover_medium.widthintegerMedia width in pixels when reported.
matched_song.cover_medium.heightintegerMedia height in pixels when reported.
matched_pgc_soundobjectMatched published sound details, when supplied.
matched_pgc_sound.titlestringMatched published sound title.
matched_pgc_sound.authorstringMatched published sound author display name.
matched_pgc_sound.cover_mediumobjectCover representation for the matched published sound.
matched_pgc_sound.cover_medium.uristringMedia identifier or URI supplied by TikTok.
matched_pgc_sound.cover_medium.url_listarrayMedia URLs returned for this representation.
matched_pgc_sound.cover_medium.url_list[]stringOne media URL for this representation.
matched_pgc_sound.cover_medium.widthintegerMedia width in pixels when reported.
matched_pgc_sound.cover_medium.heightintegerMedia height in pixels when reported.
music_release_infoobjectRelease metadata associated with the track.
music_release_info.is_new_release_songbooleanWhether the song is marked as a new release.
Added sound artists and media38 fields

data.search_item_list[].aweme_info.added_sound_music_info

FieldTypeDescription
artistsarrayArtists associated with the music, when available.
artists[]objectOne artist associated with the music.
artists[].uidstringTikTok artist account ID represented as text.
artists[].handlestringPublic TikTok username of the artist.
artists[].nick_namestringArtist display name.
artists[].is_verifiedbooleanWhether the artist account is marked as verified.
artists[].avatarobjectAvatar representation for the artist.
artists[].avatar.uristringMedia identifier or URI supplied by TikTok.
artists[].avatar.url_listarrayMedia URLs returned for this representation.
artists[].avatar.url_list[]stringOne media URL for this representation.
play_urlobjectPlayback representation for the sound.
play_url.uristringMedia identifier or URI supplied by TikTok.
play_url.url_listarrayMedia URLs returned for this representation.
play_url.url_list[]stringOne media URL for this representation.
play_url.widthintegerMedia width in pixels when reported.
play_url.heightintegerMedia height in pixels when reported.
play_url.data_sizeintegerData size value reported for this representation.
cover_largeobjectLarge music cover representation.
cover_large.uristringMedia identifier or URI supplied by TikTok.
cover_large.url_listarrayMedia URLs returned for this representation.
cover_large.url_list[]stringOne media URL for this representation.
cover_large.widthintegerMedia width in pixels when reported.
cover_large.heightintegerMedia height in pixels when reported.
cover_large.data_sizeintegerData size value reported for this representation.
cover_mediumobjectMedium music cover representation.
cover_medium.uristringMedia identifier or URI supplied by TikTok.
cover_medium.url_listarrayMedia URLs returned for this representation.
cover_medium.url_list[]stringOne media URL for this representation.
cover_medium.widthintegerMedia width in pixels when reported.
cover_medium.heightintegerMedia height in pixels when reported.
cover_medium.data_sizeintegerData size value reported for this representation.
cover_thumbobjectThumbnail music cover representation.
cover_thumb.uristringMedia identifier or URI supplied by TikTok.
cover_thumb.url_listarrayMedia URLs returned for this representation.
cover_thumb.url_list[]stringOne media URL for this representation.
cover_thumb.widthintegerMedia width in pixels when reported.
cover_thumb.heightintegerMedia height in pixels when reported.
cover_thumb.data_sizeintegerData size value reported for this representation.
Hashtags, mentions, and search highlights37 fields

data.search_item_list[].aweme_info

FieldTypeDescription
cha_listarray | nullHashtag or challenge entries associated with the post, when provided.
cha_list[]objectOne hashtag or challenge attached to the post.
cha_list[].cidstringHashtag or challenge ID represented as text.
cha_list[].cha_namestringHashtag or challenge name.
cha_list[].descstringHashtag or challenge description.
cha_list[].typeintegerNumeric tag or challenge type reported by TikTok.
cha_list[].use_countintegerUsage count reported for the hashtag or challenge.
cha_list[].user_countintegerUser count reported for the hashtag or challenge.
cha_list[].view_countintegerView count reported for the hashtag or challenge.
cha_list[].is_commercebooleanWhether the hashtag or challenge is marked as commercial.
search_highlightarrayText highlight information supplied for search results.
search_highlight[]objectOne set of highlights for a search text field.
search_highlight[].fieldstringName of the search text field to highlight.
search_highlight[].positionsarrayRanges to highlight in this text field.
search_highlight[].positions[]objectOne highlight range in this text field.
search_highlight[].positions[].beginintegerBeginning position of the highlight range.
search_highlight[].positions[].endintegerEnding position of the highlight range.
content_desc_extraarrayAnnotations for the additional post description, such as hashtags or mentions.
content_desc_extra[]objectAn annotation in the additional post description.
content_desc_extra[].startintegerStart position of the annotation in the corresponding text.
content_desc_extra[].endintegerEnd position of the annotation in the corresponding text.
content_desc_extra[].hashtag_idstringTikTok hashtag ID represented as text.
content_desc_extra[].hashtag_namestringHashtag name attached to this annotation.
content_desc_extra[].user_idstringTikTok user ID for a mention, represented as text when present.
content_desc_extra[].typeintegerNumeric annotation type returned by TikTok.
content_desc_extra[].sub_typeintegerNumeric annotation subtype returned by TikTok.
content_desc_extra[].is_commercebooleanWhether the annotation is marked as commercial.
text_extraarrayAnnotations for the post caption, such as hashtags or mentions.
text_extra[]objectAn annotation in the post caption.
text_extra[].startintegerStart position of the annotation in the corresponding text.
text_extra[].endintegerEnd position of the annotation in the corresponding text.
text_extra[].hashtag_idstringTikTok hashtag ID represented as text.
text_extra[].hashtag_namestringHashtag name attached to this annotation.
text_extra[].user_idstringTikTok user ID for a mention, represented as text when present.
text_extra[].typeintegerNumeric annotation type returned by TikTok.
text_extra[].sub_typeintegerNumeric annotation subtype returned by TikTok.
text_extra[].is_commercebooleanWhether the annotation is marked as commercial.
Visibility and interaction permissions14 fields

data.search_item_list[].aweme_info

FieldTypeDescription
statusobjectPost visibility and interaction status reported by TikTok.
status.aweme_idstringTikTok post ID associated with this status information.
status.allow_commentbooleanWhether comments are marked as allowed.
status.allow_sharebooleanWhether sharing is marked as allowed.
status.download_statusintegerNumeric download status reported for the post.
status.is_deletebooleanWhether the post is marked as deleted.
status.is_prohibitedbooleanWhether the post is marked as restricted.
status.private_statusintegerNumeric privacy status reported for the post.
interact_permissionobjectInteraction availability and permission flags for the post.
interact_permission.allow_adding_as_postobjectWhether adding the content as a post is marked as allowed.
interact_permission.allow_adding_to_storyintegerWhether adding the content to a story is marked as allowed.
interact_permission.duetintegerDuet availability flag reported for the post.
interact_permission.stitchintegerStitch availability flag reported for the post.
interact_permission.allow_create_stickerobjectWhether creating a sticker is marked as allowed.
Sharing5 fields

data.search_item_list[].aweme_info.share_info

Text and link metadata for sharing the post.

FieldTypeDescription
share_titlestringTitle supplied for sharing the post.
share_descstringDescription supplied for sharing the post.
share_link_descstringDisplay description for the post share link.
share_quotestringQuote text supplied for sharing.
share_urlstringShare URL for the post.
Places and paid content26 fields

data.search_item_list[].aweme_info

FieldTypeDescription
poi_dataobjectPublic place information attached to the post, when provided.
poi_data.poi_idstringPlace ID represented as text.
poi_data.poi_namestringPublic place name.
poi_data.location_descstringDisplay text describing the place location.
poi_data.poi_typestringPlace type reported by TikTok.
poi_data.video_countintegerVideo count reported for the place.
poi_data.address_infoobjectPublic address details attached to the place.
poi_data.address_info.city_namestringCity name reported for the place.
poi_data.address_info.region_codestringRegion code reported for the place.
poi_data.address_info.addressstringPublic address text for the place.
poi_data.thumbnailobjectThumbnail attached to the public place.
poi_data.thumbnail.uristringMedia identifier or URI supplied by TikTok.
poi_data.thumbnail.url_listarrayMedia URLs returned for this representation.
poi_data.thumbnail.url_list[]stringOne media URL for this representation.
poi_data.thumbnail.widthintegerMedia width in pixels when reported.
poi_data.thumbnail.heightintegerMedia height in pixels when reported.
paid_content_infoobjectPaid-content display metadata, when present.
paid_content_info.collection_namestringDisplay name of the paid collection.
paid_content_info.episode_numintegerEpisode number reported for the content.
paid_content_info.is_limited_freebooleanWhether the content is marked as free for a limited time.
paid_content_info.cover_urlobjectCover image metadata for the paid content.
paid_content_info.cover_url.uristringMedia identifier or URI supplied by TikTok.
paid_content_info.cover_url.url_listarrayMedia URLs returned for this representation.
paid_content_info.cover_url.url_list[]stringOne media URL for this representation.
paid_content_info.cover_url.widthintegerMedia width in pixels when reported.
paid_content_info.cover_url.heightintegerMedia height in pixels when reported.

Response Example ​

Loading the response example...