> ## Documentation Index
> Fetch the complete documentation index at: https://socialquery.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TikTok Popular Videos

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

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.


## OpenAPI

````yaml GET /tiktok/videos/popular
openapi: 3.1.0
info:
  title: SocialQuery API
  version: '2026-10-09'
  description: >-
    Documented requests for public-source records. Inspect accepted inputs and
    credit amounts, then verify the selected operation before integrating
    preview coverage.
servers:
  - url: https://socialquery.dev/v1
security:
  - apiKey: []
paths:
  /tiktok/videos/popular:
    get:
      tags:
        - TikTok
      summary: TikTok Videos Popular
      description: >-
        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.
      operationId: get_tiktok_videos_popular
      parameters:
        - name: countryCode
          in: query
          required: false
          example: US
          schema:
            type: string
            enum:
              - US
              - JP
              - VN
              - TH
              - ID
            default: US
        - name: period
          in: query
          required: false
          example: '7'
          schema:
            type: string
            enum:
              - '7'
              - '30'
            default: '7'
        - name: orderBy
          in: query
          required: false
          example: views
          schema:
            type: string
            enum:
              - views
              - engagement
              - six_second_views
            default: views
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 20
            default: 20
          description: >-
            Requested top-N board window, 1–20 (default 20). The full requested
            window is validated before date filtering; no second page is
            exposed.
        - name: since
          in: query
          required: false
          schema:
            type: string
          description: >-
            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.
        - name: until
          in: query
          required: false
          schema:
            type: string
          description: >-
            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.
        - name: Cache-Control
          in: header
          required: false
          example: no-cache
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: false
          example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c
          schema:
            type: string
        - name: X-Max-Credits
          in: header
          required: false
          description: >-
            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.
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: >-
            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.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          items:
                            type: array
                            items:
                              type: object
                              properties:
                                post:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                    url:
                                      type: string
                                      format: uri
                                    content:
                                      type: object
                                      properties:
                                        text:
                                          type: string
                                        media_urls:
                                          type:
                                            - array
                                            - 'null'
                                          items:
                                            type: string
                                            format: uri
                                          maxItems: 1
                                        thumbnail_url:
                                          type:
                                            - string
                                            - 'null'
                                        duration_seconds:
                                          type: 'null'
                                      required:
                                        - text
                                        - media_urls
                                        - thumbnail_url
                                        - duration_seconds
                                      additionalProperties: false
                                    author:
                                      type: object
                                      properties:
                                        username:
                                          type: string
                                        display_name:
                                          type: string
                                        avatar_url:
                                          type:
                                            - string
                                            - 'null'
                                        verified:
                                          type: 'null'
                                      required:
                                        - username
                                        - display_name
                                        - avatar_url
                                        - verified
                                      additionalProperties: false
                                    engagement:
                                      type: object
                                      properties:
                                        views:
                                          type: integer
                                          minimum: 0
                                        likes:
                                          type: 'null'
                                        comments:
                                          type: 'null'
                                        shares:
                                          type: 'null'
                                        saves:
                                          type: 'null'
                                      required:
                                        - views
                                        - likes
                                        - comments
                                        - shares
                                        - saves
                                      additionalProperties: false
                                    flags:
                                      type: object
                                      properties:
                                        nsfw:
                                          type: 'null'
                                        spoiler:
                                          type: 'null'
                                        pinned:
                                          type: 'null'
                                        deleted:
                                          type: boolean
                                          const: false
                                      required:
                                        - nsfw
                                        - spoiler
                                        - pinned
                                        - deleted
                                      additionalProperties: false
                                    published_at:
                                      type: string
                                      format: date-time
                                    ext:
                                      type: object
                                      properties:
                                        author_id:
                                          type: string
                                        author_followers:
                                          type: integer
                                          minimum: 0
                                        trend:
                                          type: object
                                          properties:
                                            rank:
                                              type: integer
                                              minimum: 1
                                              maximum: 20
                                            country_code:
                                              type: string
                                            period_days:
                                              type: integer
                                              enum:
                                                - 7
                                                - 30
                                            order_by:
                                              type: string
                                              enum:
                                                - views
                                                - engagement
                                                - six_second_views
                                            period_views:
                                              type: integer
                                              minimum: 0
                                            organic_views:
                                              type: integer
                                              minimum: 0
                                            engagement_rate:
                                              type: number
                                              minimum: 0
                                              maximum: 1
                                            six_second_view_through_rate:
                                              type: number
                                              minimum: 0
                                              maximum: 1
                                            content_tags:
                                              type: array
                                              items:
                                                type: string
                                              maxItems: 100
                                          required:
                                            - rank
                                            - country_code
                                            - period_days
                                            - order_by
                                            - period_views
                                            - organic_views
                                            - engagement_rate
                                            - six_second_view_through_rate
                                            - content_tags
                                          additionalProperties: false
                                      required:
                                        - author_id
                                        - author_followers
                                        - trend
                                      additionalProperties: false
                                  required:
                                    - id
                                    - url
                                    - content
                                    - author
                                    - engagement
                                    - flags
                                    - published_at
                                    - ext
                                  additionalProperties: false
                              required:
                                - post
                              additionalProperties: false
                            maxItems: 20
                          total:
                            type: integer
                            minimum: 0
                          returned_count:
                            type: integer
                            minimum: 0
                          source_count:
                            type: integer
                            minimum: 0
                          dropped:
                            type: integer
                            minimum: 0
                          requested_limit:
                            type: integer
                            minimum: 1
                            maximum: 20
                          country_code:
                            type: string
                          period_days:
                            type: integer
                            enum:
                              - 7
                              - 30
                          order_by:
                            type: string
                          has_more:
                            type: boolean
                            const: false
                          next_cursor:
                            type: 'null'
                          coverage_note:
                            type: string
                        required:
                          - items
                          - total
                          - returned_count
                          - source_count
                          - dropped
                          - requested_limit
                          - country_code
                          - period_days
                          - order_by
                          - has_more
                          - next_cursor
                          - coverage_note
                        additionalProperties: false
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
        '504':
          $ref: '#/components/responses/Error504'
components:
  schemas:
    SocialQueryResponse:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - data
      properties:
        success:
          type: boolean
          const: true
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        data:
          type: object
          additionalProperties: true
          description: >-
            The selected operation determines the resource fields in this
            object. Source data can omit a metric or report it as null.
    SocialQueryError:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - error
      properties:
        success:
          type: boolean
          const: false
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        error:
          type: object
          required:
            - code
            - type
            - message
            - status
            - doc_url
          properties:
            code:
              type: string
            type:
              type: string
            message:
              type: string
            status:
              type: integer
            doc_url:
              type: string
              format: uri
  responses:
    Error400:
      description: Upstream rejected the request.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error401:
      description: Missing, expired, invalid, or revoked API key.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error402:
      description: Insufficient SocialQuery credits.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error403:
      description: Key scope or provider policy denied access.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error404:
      description: Endpoint or upstream resource not found.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error405:
      description: HTTP method is not supported.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error409:
      description: Idempotency conflict or request in progress.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error422:
      description: Invalid parameters.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error429:
      description: Request limit reached.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error500:
      description: Request processing failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error502:
      description: Upstream service failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error503:
      description: Provider or required service is unavailable.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error504:
      description: Upstream service timed out.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.