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

# YouTube Video Comment Replies

> Replies to a public top-level YouTube comment. Pass a top-level comment ID for the first page and the returned data.next_cursor unchanged for subsequent pages. The configured official provider returns up to ten replies per page. Label judgments and date filtering are not implemented; explicit unsupported options return 422. This operation does not provide downloaded media or transcript access.

Read replies through the [official YouTube comments API](https://developers.google.com/youtube/v3/docs/comments/list). Start with a top-level `id` returned by `/v1/youtube/video/comments`, using `continuationToken`. The returned `data.next_cursor` can be passed unchanged as either `continuationToken` or `cursor` for the next page. Tokens from other providers are not interchangeable.

The current adapter returns up to ten replies per page. `data.returned_count` is the current page size; `total` is the provider's reported total when present, otherwise null. `has_more` follows the returned cursor. Parent IDs are checked on every reply. `format` accepts `html` (default) or `plainText`; callers rendering HTML should sanitize it.

Fresh successful pages cost **1 SocialQuery credit**. Cache hits and successful idempotent replays cost zero; failed calls are refunded. Use `X-Max-Credits: 1`.

Judgments are not yet implemented: the default response reports skipped labels and null values. `judgments=off` or `label=none` omits judgment fields. Explicit labeling, date filters, fitting and dry-run requests return 422. Reply counts and account verification remain null when the provider does not supply them. This verifies public reply access and pagination, not full SocialCrawl enrichment parity.


## OpenAPI

````yaml GET /youtube/video/comment/replies
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:
  /youtube/video/comment/replies:
    get:
      tags:
        - YouTube
      summary: YouTube Video Comment Replies
      description: >-
        Replies to a public top-level YouTube comment. Pass a top-level comment
        ID for the first page and the returned data.next_cursor unchanged for
        subsequent pages. The configured official provider returns up to ten
        replies per page. Label judgments and date filtering are not
        implemented; explicit unsupported options return 422. This operation
        does not provide downloaded media or transcript access.
      operationId: get_youtube_video_comment_replies
      parameters:
        - name: continuationToken
          in: query
          required: false
          example: Ugw1tpIYg_PAwdPneep4AaABAg
          schema:
            type: string
          description: >-
            Top-level comment ID or data.next_cursor returned by this operation.
            Required unless cursor is supplied.
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum:
              - html
              - plainText
          description: 'Reply text format: html (default) or plainText.'
        - name: label
          in: query
          required: false
          schema:
            type: string
          description: >-
            Only none is supported to omit judgment fields. Other label presets
            return 422.
        - name: exclude
          in: query
          required: false
          schema:
            type: string
          description: >-
            Unsupported by this configured provider; returns 422 rather than
            silently ignoring the requested behavior.
        - name: judgments
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'on'
              - 'off'
          description: >-
            off omits computed judgment fields. Without this option, labels
            remain null with a skipped status; explicit on is unsupported.
        - name: dry_run
          in: query
          required: false
          schema:
            type: string
            enum:
              - '1'
          description: >-
            Unsupported by this configured provider; returns 422 rather than
            silently ignoring the requested behavior.
        - name: label_evidence
          in: query
          required: false
          schema:
            type: string
            enum:
              - '1'
          description: >-
            Unsupported by this configured provider; returns 422 rather than
            silently ignoring the requested behavior.
        - name: fit
          in: query
          required: false
          schema:
            type: string
            enum:
              - goal
          description: >-
            Unsupported by this configured provider; returns 422 rather than
            silently ignoring the requested behavior.
        - name: goal
          in: query
          required: false
          schema:
            type: string
          description: >-
            Unsupported by this configured provider; returns 422 rather than
            silently ignoring the requested behavior.
        - name: fit_tokens
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Unsupported by this configured provider; returns 422 rather than
            silently ignoring the requested behavior.
        - name: since
          in: query
          required: false
          schema:
            type: string
          description: >-
            Unsupported by this configured provider; returns 422 rather than
            silently ignoring the requested behavior.
        - name: until
          in: query
          required: false
          schema:
            type: string
          description: >-
            Unsupported by this configured provider; returns 422 rather than
            silently ignoring the requested behavior.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            Exact data.next_cursor returned by the previous replies call; it
            carries the original parent comment and provider page token.
        - 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: >-
            Replies to a public top-level YouTube comment. Pass a top-level
            comment ID for the first page and the returned data.next_cursor
            unchanged for subsequent pages. The configured official provider
            returns up to ten replies per page. Label judgments and date
            filtering are not implemented; explicit unsupported options return
            422. This operation does not provide downloaded media or transcript
            access.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          items:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                text:
                                  type:
                                    - string
                                    - 'null'
                                parent_id:
                                  type: string
                                post_id:
                                  type:
                                    - string
                                    - 'null'
                                published_at:
                                  type:
                                    - string
                                    - 'null'
                                updated_at:
                                  type:
                                    - string
                                    - 'null'
                                author:
                                  type: object
                                  properties:
                                    id:
                                      type:
                                        - string
                                        - 'null'
                                    username:
                                      type: 'null'
                                    display_name:
                                      type:
                                        - string
                                        - 'null'
                                    avatar_url:
                                      type:
                                        - string
                                        - 'null'
                                    verified:
                                      type: 'null'
                                engagement:
                                  type: object
                                  properties:
                                    likes:
                                      type:
                                        - number
                                        - 'null'
                                    replies:
                                      type: 'null'
                                computed:
                                  type: object
                                  properties:
                                    labels:
                                      type: 'null'
                          parent_id:
                            type: string
                          returned_count:
                            type: integer
                          total:
                            type:
                              - integer
                              - 'null'
                          next_cursor:
                            type:
                              - string
                              - 'null'
                          has_more:
                            type: boolean
                          labels:
                            type: object
                            properties:
                              status:
                                type: string
                                enum:
                                  - skipped
                              reason:
                                type: string
        '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.