> ## 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 Post Comments

> Current public comment window from a canonical post URL. One provider page per request, at most three pages or 200 remembered IDs. Instagram supports top (small non-paginated window) and recent; TikTok retains native order and rejects explicit sort. Dates filter comment publication on the current page. Reply counts are retained but replies/enrichments/page scanning are not implemented. Trial capacity is capped and ends October 19, 2026 UTC; unsupported parameters and source failures do not incur a net SocialQuery charge.

Pass a canonical public post `url`. The current source preserves native comment order. An explicit `sort` is rejected because this source does not implement the requested ordering.

Each response contains one source page in `items[].comment`, including the comment ID, post ID, author, text, publication time and available like/reply counts. Missing values are null, including reply bodies: a reply count does not mean replies were fetched.

Return `next_cursor` unchanged with the same URL, sort and date filters to continue. Cursors are bound to those inputs and deduplicate earlier pages. The current adapter allows at most three pages or 200 remembered IDs. If more source data remains at that boundary, `truncated` and `source_has_more` are true and `next_cursor` is null. A missing cursor alone does not establish that every historical comment was retrieved.

`since` and `until` accept inclusive YYYY-MM-DD comment-publication dates. They filter the current source page; a filtered empty page can still have a cursor. Enrichments, reply expansion, classification and `scan_pages` are unavailable and return 422. This is a changing public window, not a complete archive.

<Note>The EnsembleData trial shares 50 provider units per rolling day and stops October 19, 2026 UTC. Failed reservations block source calls. Instagram reserves four units per page, including a fresh shortcode-to-media identity check; TikTok reserves one. These provider units are separate from SocialQuery's documented customer credit price. No paid source plan or automatic renewal is enabled.</Note>

Fresh successful pages use the documented customer credit price; cached responses and successful idempotent replays are free. Malformed or mismatched source responses fail without a net customer charge.


## OpenAPI

````yaml GET /tiktok/post/comments
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/post/comments:
    get:
      tags:
        - TikTok
      summary: TikTok Post Comments
      description: >-
        Current public comment window from a canonical post URL. One provider
        page per request, at most three pages or 200 remembered IDs. Instagram
        supports top (small non-paginated window) and recent; TikTok retains
        native order and rejects explicit sort. Dates filter comment publication
        on the current page. Reply counts are retained but
        replies/enrichments/page scanning are not implemented. Trial capacity is
        capped and ends October 19, 2026 UTC; unsupported parameters and source
        failures do not incur a net SocialQuery charge.
      operationId: get_tiktok_post_comments
      parameters:
        - name: url
          in: query
          required: true
          example: https://www.tiktok.com/@stoolpresidente/video/7623818255903329566
          schema:
            type: string
        - name: cursor
          in: query
          required: false
          schema:
            type: string
        - name: trim
          in: query
          required: false
          schema:
            type: boolean
        - name: sort
          in: query
          required: false
          schema:
            type: string
            enum:
              - top
              - recent
        - name: scan_pages
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 3
        - name: label
          in: query
          required: false
          schema:
            type: string
        - name: exclude
          in: query
          required: false
          schema:
            type: string
        - name: judgments
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'on'
              - 'off'
        - name: dry_run
          in: query
          required: false
          schema:
            type: string
            enum:
              - '1'
        - name: label_evidence
          in: query
          required: false
          schema:
            type: string
            enum:
              - '1'
        - name: fit
          in: query
          required: false
          schema:
            type: string
            enum:
              - goal
        - name: goal
          in: query
          required: false
          schema:
            type: string
        - name: fit_tokens
          in: query
          required: false
          schema:
            type: integer
        - 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
      responses:
        '200':
          description: >-
            Normalized public comment page with explicit continuation and
            truncation state.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          items:
                            type: array
                            items:
                              type: object
                              properties:
                                comment:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                    post_id:
                                      type: string
                                    text:
                                      type:
                                        - string
                                        - 'null'
                                    author:
                                      type: object
                                      properties:
                                        id:
                                          type: string
                                        username:
                                          type: string
                                        display_name:
                                          type:
                                            - string
                                            - 'null'
                                        verified:
                                          type:
                                            - boolean
                                            - 'null'
                                      required:
                                        - id
                                        - username
                                        - display_name
                                        - verified
                                    engagement:
                                      type: object
                                      properties:
                                        likes:
                                          type:
                                            - integer
                                            - 'null'
                                          minimum: 0
                                        replies:
                                          type:
                                            - integer
                                            - 'null'
                                          minimum: 0
                                      required:
                                        - likes
                                        - replies
                                    published_at:
                                      type: string
                                      format: date-time
                                    parent_comment_id:
                                      type:
                                        - string
                                        - 'null'
                                    replies:
                                      type: 'null'
                                  required:
                                    - id
                                    - post_id
                                    - text
                                    - author
                                    - engagement
                                    - published_at
                                    - parent_comment_id
                                    - replies
                              required:
                                - comment
                          returned_count:
                            type: integer
                            minimum: 0
                          total:
                            type:
                              - integer
                              - 'null'
                            minimum: 0
                          next_cursor:
                            type:
                              - string
                              - 'null'
                          source_has_more:
                            type: boolean
                          truncated:
                            type: boolean
                          page:
                            type: integer
                            minimum: 1
                            maximum: 3
                          sort:
                            type: string
                            enum:
                              - top
                              - recent
                              - native
                          post_id:
                            type: string
                          coverage_note:
                            type: string
                        required:
                          - items
                          - returned_count
                          - total
                          - next_cursor
                          - source_has_more
                          - truncated
                          - page
                          - sort
                          - post_id
                          - coverage_note
        '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.