> ## 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 profile playlists

> List the complete available public playlist directory for a corroborated TikTok handle or numeric user ID. Each playlist preserves its source ID, name and video count. Reads at most three 30-playlist pages after resolving the profile, within 45 seconds. An unfinished directory fails uncharged instead of returning a partial list. Dates and engagement are unavailable and remain null; undated playlists are kept under date filters. This endpoint does not return playable video files.

Pass a `handle` (with or without `@`) or a numeric `user_id`. If both are supplied, both must match the resolved public profile. Costs **1 credit** on a successful nonempty response. Errors, empty directories, cache hits and successful idempotent replays cost zero. Use `X-Max-Credits: 1` to cap the charge.

The response contains each playlist's native ID, name and `post.ext.video_count`, in source order. It resolves the profile first, verifies playlist ownership, then walks the available directory to its end. The request is bounded to three pages of 30 playlists and 45 seconds. A directory that exceeds this ceiling returns an uncharged **503 `LOOKUP_SCAN_LIMIT`**; it is never presented as a complete partial list. `total` counts the returned available directory, not private or deleted playlists.

The source does not publish playlist timestamps or engagement totals. Those fields, verification badges and computed estimates remain null. `since` and `until` accept calendar dates or ISO timestamps with timezones; undated rows are retained. Date aliases `published_after`, `start_date`, `from_date`, `published_before`, `end_date` and `to_date` must agree with explicit bounds. Relative `publish_time` and `max_age_days` bounds are also accepted. Because playlist dates are unknown, these filters usually retain the whole directory.

This endpoint supplies playlist metadata. Video playback through `/v1/tiktok/playlist/videos` remains unavailable: a tested source media URL returned 403. It is not advertised as a working download route.

Source: [TikHub public API](https://api.tikhub.io/), using the existing free-trial allowance shared with comment lookup. Trial limits are finite. Successful directories may be cached for five minutes; `Cache-Control: no-cache` requests a fresh read.


## OpenAPI

````yaml GET /tiktok/profile/playlists
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/profile/playlists:
    get:
      tags:
        - TikTok
      summary: List a TikTok profile’s public playlists
      description: >-
        List the complete available public playlist directory for a corroborated
        TikTok handle or numeric user ID. Each playlist preserves its source ID,
        name and video count. Reads at most three 30-playlist pages after
        resolving the profile, within 45 seconds. An unfinished directory fails
        uncharged instead of returning a partial list. Dates and engagement are
        unavailable and remain null; undated playlists are kept under date
        filters. This endpoint does not return playable video files.
      operationId: get_tiktok_profile_playlists
      parameters:
        - name: handle
          in: query
          required: false
          example: chipotle
          schema:
            type: string
        - name: user_id
          in: query
          required: false
          schema:
            type: string
        - name: since
          in: query
          required: false
          schema:
            type: string
        - name: until
          in: query
          required: false
          schema:
            type: string
        - 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
        - name: published_after
          in: query
          required: false
          schema:
            type: string
          description: >-
            Date-filter alias. Undated playlist rows are kept. Explicit date
            aliases must agree. publish_time accepts yesterday, this-week,
            this-month, last-3-months or last-6-months; max_age_days accepts
            0–36500.
        - name: start_date
          in: query
          required: false
          schema:
            type: string
          description: >-
            Date-filter alias. Undated playlist rows are kept. Explicit date
            aliases must agree. publish_time accepts yesterday, this-week,
            this-month, last-3-months or last-6-months; max_age_days accepts
            0–36500.
        - name: from_date
          in: query
          required: false
          schema:
            type: string
          description: >-
            Date-filter alias. Undated playlist rows are kept. Explicit date
            aliases must agree. publish_time accepts yesterday, this-week,
            this-month, last-3-months or last-6-months; max_age_days accepts
            0–36500.
        - name: published_before
          in: query
          required: false
          schema:
            type: string
          description: >-
            Date-filter alias. Undated playlist rows are kept. Explicit date
            aliases must agree. publish_time accepts yesterday, this-week,
            this-month, last-3-months or last-6-months; max_age_days accepts
            0–36500.
        - name: end_date
          in: query
          required: false
          schema:
            type: string
          description: >-
            Date-filter alias. Undated playlist rows are kept. Explicit date
            aliases must agree. publish_time accepts yesterday, this-week,
            this-month, last-3-months or last-6-months; max_age_days accepts
            0–36500.
        - name: to_date
          in: query
          required: false
          schema:
            type: string
          description: >-
            Date-filter alias. Undated playlist rows are kept. Explicit date
            aliases must agree. publish_time accepts yesterday, this-week,
            this-month, last-3-months or last-6-months; max_age_days accepts
            0–36500.
        - name: publish_time
          in: query
          required: false
          schema:
            type: string
          description: >-
            Date-filter alias. Undated playlist rows are kept. Explicit date
            aliases must agree. publish_time accepts yesterday, this-week,
            this-month, last-3-months or last-6-months; max_age_days accepts
            0–36500.
        - name: max_age_days
          in: query
          required: false
          schema:
            type: string
          description: >-
            Date-filter alias. Undated playlist rows are kept. Explicit date
            aliases must agree. publish_time accepts yesterday, this-week,
            this-month, last-3-months or last-6-months; max_age_days accepts
            0–36500.
      responses:
        '200':
          description: >-
            List the complete available public playlist directory for a
            corroborated TikTok handle or numeric user ID. Each playlist
            preserves its source ID, name and video count. Reads at most three
            30-playlist pages after resolving the profile, within 45 seconds. An
            unfinished directory fails uncharged instead of returning a partial
            list. Dates and engagement are unavailable and remain null; undated
            playlists are kept under date filters. This endpoint does not return
            playable video files.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          items:
                            type: array
                            maxItems: 90
                            items:
                              type: object
                              properties:
                                post:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                    url:
                                      type: 'null'
                                    content:
                                      type: object
                                      properties:
                                        text:
                                          type: string
                                        media_urls:
                                          type: 'null'
                                        thumbnail_url:
                                          type: 'null'
                                        duration_seconds:
                                          type: 'null'
                                      required:
                                        - text
                                        - media_urls
                                        - thumbnail_url
                                        - duration_seconds
                                      additionalProperties: false
                                    author:
                                      type: object
                                      properties:
                                        id:
                                          type: string
                                        username:
                                          type: string
                                        display_name:
                                          type: 'null'
                                        avatar_url:
                                          type: 'null'
                                        verified:
                                          type: 'null'
                                      required:
                                        - id
                                        - username
                                        - display_name
                                        - avatar_url
                                        - verified
                                      additionalProperties: false
                                    engagement:
                                      type: object
                                      properties:
                                        views:
                                          type: 'null'
                                        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:
                                          const: false
                                      required:
                                        - nsfw
                                        - spoiler
                                        - pinned
                                        - deleted
                                      additionalProperties: false
                                    published_at:
                                      type: 'null'
                                    ext:
                                      type: object
                                      properties:
                                        video_count:
                                          type: integer
                                          minimum: 0
                                      required:
                                        - video_count
                                      additionalProperties: false
                                  required:
                                    - id
                                    - url
                                    - content
                                    - author
                                    - engagement
                                    - flags
                                    - published_at
                                    - ext
                                  additionalProperties: false
                                computed:
                                  type: object
                                  properties:
                                    engagement_rate:
                                      type: 'null'
                                    language:
                                      type: 'null'
                                    content_category:
                                      type: 'null'
                                    estimated_reach:
                                      type: 'null'
                                  required:
                                    - engagement_rate
                                    - language
                                    - content_category
                                    - estimated_reach
                                  additionalProperties: false
                              required:
                                - post
                                - computed
                              additionalProperties: false
                          total:
                            type: integer
                            minimum: 0
                          next_cursor:
                            type: 'null'
                          dropped:
                            const: 0
                          user_id:
                            type: string
                          username:
                            type: string
                          pages_scanned:
                            type: integer
                            minimum: 1
                            maximum: 3
                          source:
                            type: string
                          coverage_note:
                            type: string
                        required:
                          - items
                          - total
                          - next_cursor
                          - dropped
                          - user_id
                          - username
                          - pages_scanned
                          - source
                          - coverage_note
                        additionalProperties: false
                    required:
                      - data
        '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.