openapi: 3.0.0
info:
  title: TikTok Comments API
  description: |
    The TikTok Comments API retrieves the comments on a public TikTok video or photo post, or the replies
    to one of its comments, from the post's URL or numeric id.

    Comments are returned a page at a time. The first few hundred come in the order TikTok ranks them,
    and the rest follow unranked. Each response carries a `pagination.next_page_token` while more
    remain. Pass it back as `next_page_token` to fetch the next page. The token identifies the video
    and comment on its own, so the other parameters may be omitted on a paging request. Pages can repeat
    comments from earlier pages; use `id` to tell them apart.

    Each comment includes its text, like count, reply count, timestamp, language, pinned and
    liked-by-creator flags, the picture for image and sticker comments, and the author's public profile. To
    list the replies to a comment, pass its `id` as `comment_id`, and the response then carries
    `parent_comment` and the replies in `comments`. A reply to another reply names it in `reply_to`.

    **Cross-linking**: Each `video.link` is a valid `url` for the TikTok Video API, which returns the
    video's own details and stats, and each author's `username` is the `username` of the TikTok Profile
    API.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: TikTok Comments
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine identifier
          schema:
            type: string
            enum: ["tiktok_comments"]
            default: "tiktok_comments"
        - name: url
          in: query
          required: false
          description: >-
            Full URL of the TikTok video or photo post, such as
            https://www.tiktok.com/@stoolpresidente/video/7499229683859426602. Short vm.tiktok.com,
            vt.tiktok.com and tiktok.com/t/ links are not accepted. Required unless video_id or
            next_page_token is provided.
          schema:
            type: string
        - name: video_id
          in: query
          required: false
          description: >-
            Numeric id of the TikTok video or photo post, the number at the end of its URL. Required
            unless url or next_page_token is provided. Cannot be combined with url.
          schema:
            type: string
            pattern: '^\d{1,19}$'
        - name: comment_id
          in: query
          required: false
          description: >-
            Numeric id of a comment on the video, taken from a previous response's comments. When set,
            the response lists the replies to that comment instead of the video's comments.
          schema:
            type: string
            pattern: '^\d{1,19}$'
        - name: next_page_token
          in: query
          required: false
          description: >-
            Opaque cursor for the next page. Take it from pagination.next_page_token in a previous
            response and pass it back to page forward. Omit it for the first page.
          schema:
            type: string
      responses:
        '200':
          description: >-
            Successful response. When the list has nothing to show (a private or deleted video, comments
            turned off, an incorrect id, no comments yet, a comment_id with no replies, or a page past the
            end of the list), the body carries `error`
            naming the reason in place of `video`, `comments` and `pagination`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout, or TikTok answered but returned nothing usable. The search is not billed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        video:
          $ref: '#/components/schemas/Video'
        parent_comment:
          $ref: '#/components/schemas/ParentComment'
        comments:
          type: array
          description: The comments on the video for this page, or the replies to comment_id
          items:
            $ref: '#/components/schemas/Comment'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Message naming why the list has nothing to show
    Video:
      type: object
      required: [id, link]
      properties:
        id:
          type: string
          description: Numeric id of the video
        link:
          type: string
          format: uri
          description: URL of the video page
        comments:
          type: integer
          description: Comment count TikTok displays for the video, which includes replies and can exceed the comments the list returns
    ParentComment:
      type: object
      description: The comment whose replies are listed
      required: [id, replies]
      properties:
        id:
          type: string
          description: Numeric id of the comment
        replies:
          type: integer
          description: Number of replies TikTok lists for the comment, across all pages
    Comment:
      type: object
      required: [position, id, likes, iso_date, author]
      properties:
        position:
          type: integer
          description: Position of the comment in the returned list, starting at 1
        id:
          type: string
          description: Numeric id of the comment, usable as comment_id to list its replies
        text:
          type: string
          description: Body of the comment
        image:
          type: string
          format: uri
          description: Full-size URL of the picture or sticker the comment was posted with
        likes:
          type: integer
          description: Number of likes on the comment
        replies:
          type: integer
          description: Number of replies to the comment
        iso_date:
          type: string
          format: date-time
          description: Time the comment was posted, in UTC
        language:
          type: string
          description: Language code TikTok detected for the comment text
        is_pinned:
          type: boolean
          description: Whether the creator pinned the comment
        is_liked_by_creator:
          type: boolean
          description: Whether the video's creator liked the comment
        reply_to:
          $ref: '#/components/schemas/ReplyTo'
        author:
          $ref: '#/components/schemas/Author'
    ReplyTo:
      type: object
      description: The reply this reply answers
      required: [id]
      properties:
        id:
          type: string
          description: Numeric id of the reply it answers
        username:
          type: string
          description: TikTok handle of that reply's author
        name:
          type: string
          description: Display name of that reply's author
    Author:
      type: object
      description: Public profile of the comment's author
      required: [id, username, link, name, avatar]
      properties:
        id:
          type: string
          description: Numeric id of the author
        username:
          type: string
          description: TikTok handle of the author, usable as the username of the TikTok Profile API
        link:
          type: string
          format: uri
          description: URL of the author's profile page
        name:
          type: string
          description: Display name of the author
        avatar:
          type: string
          format: uri
          description: URL of the author's profile picture
        is_verified:
          type: boolean
          description: Whether the author's account is verified
    Pagination:
      type: object
      properties:
        next_page_token:
          type: string
          description: Cursor for the next page of the same list
    SearchMetadata:
      type: object
      required: [id, status, created_at]
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: TikTok video URL for this search
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Search engine identifier
        url:
          type: string
          description: Video URL the comments were requested with
        video_id:
          type: string
          description: Video id the comments were requested with
        comment_id:
          type: string
          description: Comment id whose replies were requested
        next_page_token:
          type: string
          description: Cursor of the requested page
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong