TikTok Popular Videos

TikTok Videos Popular

curl --request GET \
  --url https://socialquery.dev/v1/tiktok/videos/popular \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://socialquery.dev/v1/tiktok/videos/popular', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "data": {
    "items": [
      {
        "post": {
          "id": "<string>",
          "url": "<string>",
          "content": {
            "text": "<string>",
            "media_urls": [
              "<string>"
            ],
            "thumbnail_url": "<string>",
            "duration_seconds": null
          },
          "author": {
            "username": "<string>",
            "display_name": "<string>",
            "avatar_url": "<string>",
            "verified": null
          },
          "engagement": {
            "views": 1,
            "likes": null,
            "comments": null,
            "shares": null,
            "saves": null
          },
          "flags": {
            "nsfw": null,
            "spoiler": null,
            "pinned": null,
            "deleted": false
          },
          "published_at": "2023-11-07T05:31:56Z",
          "ext": {
            "author_id": "<string>",
            "author_followers": 1,
            "trend": {
              "rank": 10,
              "country_code": "<string>",
              "period_days": 7,
              "order_by": "views",
              "period_views": 1,
              "organic_views": 1,
              "engagement_rate": 0.5,
              "six_second_view_through_rate": 0.5,
              "content_tags": [
                "<string>"
              ]
            }
          }
        }
      }
    ],
    "total": 1,
    "returned_count": 1,
    "source_count": 1,
    "dropped": 1,
    "requested_limit": 10,
    "country_code": "<string>",
    "period_days": 7,
    "order_by": "<string>",
    "has_more": false,
    "next_cursor": null,
    "coverage_note": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

GET

tiktok

videos

popular

TikTok Videos Popular

curl --request GET \
  --url https://socialquery.dev/v1/tiktok/videos/popular \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://socialquery.dev/v1/tiktok/videos/popular', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "data": {
    "items": [
      {
        "post": {
          "id": "<string>",
          "url": "<string>",
          "content": {
            "text": "<string>",
            "media_urls": [
              "<string>"
            ],
            "thumbnail_url": "<string>",
            "duration_seconds": null
          },
          "author": {
            "username": "<string>",
            "display_name": "<string>",
            "avatar_url": "<string>",
            "verified": null
          },
          "engagement": {
            "views": 1,
            "likes": null,
            "comments": null,
            "shares": null,
            "saves": null
          },
          "flags": {
            "nsfw": null,
            "spoiler": null,
            "pinned": null,
            "deleted": false
          },
          "published_at": "2023-11-07T05:31:56Z",
          "ext": {
            "author_id": "<string>",
            "author_followers": 1,
            "trend": {
              "rank": 10,
              "country_code": "<string>",
              "period_days": 7,
              "order_by": "views",
              "period_views": 1,
              "organic_views": 1,
              "engagement_rate": 0.5,
              "six_second_view_through_rate": 0.5,
              "content_tags": [
                "<string>"
              ]
            }
          }
        }
      }
    ],
    "total": 1,
    "returned_count": 1,
    "source_count": 1,
    "dropped": 1,
    "requested_limit": 10,
    "country_code": "<string>",
    "period_days": 7,
    "order_by": "<string>",
    "has_more": false,
    "next_cursor": null,
    "coverage_note": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

Read TikTok’s top-video board for US, JP, VN, TH or ID. The default is US, last 7 days, highest views, top 20. period also accepts 30; orderBy also accepts engagement or six_second_views. Other markets and separate like/comment/share sorts are rejected before source work. Each items[].post includes the native video ID, canonical URL, caption, cover, available signed video-file URL, creator identity, publication time and lifetime views. post.ext.trend preserves rank, period views, organic views, engagement rate, six-second view-through rate and content tags. Period views are not lifetime views. Like/comment/share counts, duration and verification status are unavailable and remain null. The board may contain paid or branded posts; organic views are the supplied organic signal. Media links expire; SocialQuery returns them without downloading or rehosting the media. limit selects a top-N window from 1 to 20. Every source row must have a distinct native ID, consecutive rank, the requested country/period/sort and valid source metrics. A shortened or inconsistent dataset fails unbilled instead of being presented as a complete or empty board. There is no cursor or deeper-history search. since and until filter publication timestamps inside that requested window, inclusively. An ISO until date includes the whole UTC day; timezone-qualified timestamps are used exactly. Filtering preserves native ranks, so visible ranks may skip numbers. source_count is the verified window before filtering, dropped is the number removed, and returned_count is the final number of rows. A date-filtered empty result is free. Pricing: 25 credits per board plus 1 per returned video. The default top-20 request reserves 45 credits; limit 4 reserves 29. Date filtering refunds unused per-video credits, and a completely empty filtered result refunds the entire hold. Failed reads, cache hits and successful idempotent replays cost zero. Supply X-Max-Credits for the full requested hold, even if date filters may reduce the final charge. The source run is pinned, uses limited permissions and has a 50-second execution limit within a 55-second read deadline. This is a bounded live ranking, not a guarantee that every country and sort will remain available at all times.

Authorizations

x-api-key

string

header

required

Headers

Cache-Control

string

Idempotency-Key

string

X-Max-Credits

integer

Optional nonnegative integer cap on the maximum request hold. A live request whose hold exceeds this cap returns 422 CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the requested limit; cache hits and successful idempotent replays cost zero.

Required range: x >= 0

Query Parameters

countryCode

enum<string>

default:US

Available options:

US,

JP,

VN,

TH,

ID

period

enum<string>

default:7

Available options:

7,

30

orderBy

enum<string>

default:views

Available options:

views,

engagement,

six_second_views

limit

integer

default:20

Requested top-N board window, 1–20 (default 20). The full requested window is validated before date filtering; no second page is exposed.

Required range: 1 <= x <= 20

since

string

Optional inclusive publication-date bound within the requested top-N window. Accepts ISO dates or timezone-qualified timestamps; an until date includes the entire UTC day. It does not search deeper history.

until

string

Response

Read the complete requested top-N TikTok video board, up to 20 rows, for US, JP, VN, TH or ID over 7 or 30 days. Sort by views, engagement or six-second view rate. Preserve native rank, lifetime versus period views, publication times and signed media links. A truncated or inconsistent source fails without charge.

success

boolean

required

platform

string

required

endpoint

string

required

credits_used

integer

required

Required range: x >= 0

credits_remaining

integer | null

required

request_id

string

required

cached

boolean

required

data

object

required

The selected operation determines the resource fields in this object. Source data can omit a metric or report it as null.

Show child attributes