openapi: 3.0.0
info:
  title: TikTok Profile Followers API
  description: |
    Retrieve the followers of a public TikTok account by username. The response carries a profile summary
    with the account's exact follower count, and a page of up to 30 followers, most recent first, each with
    its username, display name, avatar, verification and privacy flags, and follower, following, hearts and
    video counts. Pages run newest to oldest through next_page_token, and TikTok lists only an account's
    most recent followers.

    **Cross-linking**: The username comes from the TikTok Profile or TikTok Search API. Pass a follower's
    username to the TikTok Profile API for the full profile, to the TikTok Profile Videos API for their
    video feed, or back to this API for their own followers.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: TikTok Profile Followers Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine identifier
          schema:
            type: string
            enum: ["tiktok_profile_followers"]
            default: "tiktok_profile_followers"
        - name: username
          in: query
          required: false
          description: TikTok username (with or without the @ symbol). Required unless `next_page_token` is provided.
          schema:
            type: string
            pattern: '^@?[a-zA-Z0-9_.]{1,24}$'
        - name: next_page_token
          in: query
          required: false
          description: Token to retrieve the next page of followers, taken from pagination.next_page_token of the previous response.
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          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. We could not retrieve results in 90 seconds.
          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'
        profile:
          $ref: '#/components/schemas/Profile'
        followers:
          type: array
          description: The page of accounts that follow this profile, most recent first.
          items:
            $ref: '#/components/schemas/Follower'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Error message for a username that does not exist, an account whose follower list is private or empty, a profile that requires login to view, or a page past the followers TikTok lists.

    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 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
        username:
          type: string
          description: TikTok username
        next_page_token:
          type: string
          description: Pagination token used for this request

    Profile:
      type: object
      required: [username, link]
      properties:
        id:
          type: string
          description: TikTok numeric user ID.
        sec_uid:
          type: string
          description: TikTok secure user ID.
        username:
          type: string
          description: TikTok username.
        link:
          type: string
          description: URL to the profile page.
        name:
          type: string
          description: Display name.
        bio:
          type: string
          description: Profile bio.
        avatar:
          type: string
          description: URL to the profile avatar image.
        avatar_hd:
          type: string
          description: URL to a high-resolution version of the profile avatar image.
        is_verified:
          type: boolean
          description: Whether the account is verified.
        is_private:
          type: boolean
          description: Whether the account is private.
        followers:
          type: integer
          description: Exact number of followers.
        following:
          type: integer
          description: Number of accounts this profile follows.
        hearts:
          type: integer
          description: Total hearts (likes) received across all videos.
        posts:
          type: integer
          description: Total number of videos posted.

    Follower:
      type: object
      required: [position, id, sec_uid, username, link, name, avatar, followers, following, hearts, posts]
      properties:
        position:
          type: integer
          description: 1-based position of the follower in the returned page.
        id:
          type: string
          description: TikTok numeric user ID of the follower.
        sec_uid:
          type: string
          description: TikTok secure user ID of the follower.
        username:
          type: string
          description: The follower's TikTok username.
        link:
          type: string
          description: URL to the follower's profile page.
        name:
          type: string
          description: The follower's display name.
        bio:
          type: string
          description: The follower's profile bio.
        avatar:
          type: string
          description: URL to the follower's avatar image.
        avatar_hd:
          type: string
          description: URL to a high-resolution version of the follower's avatar image.
        is_verified:
          type: boolean
          description: Whether the follower's account is verified.
        is_private:
          type: boolean
          description: Whether the follower's account is private.
        followers:
          type: integer
          description: Number of accounts that follow this follower.
        following:
          type: integer
          description: Number of accounts this follower follows.
        hearts:
          type: integer
          description: Total hearts (likes) the follower has received across all videos.
        posts:
          type: integer
          description: Number of videos the follower has posted.
        is_seller:
          type: boolean
          description: Whether the account is a TikTok Shop seller.
        liked_videos:
          type: integer
          description: Number of videos the account has liked.

    Pagination:
      type: object
      properties:
        has_more:
          type: boolean
          description: Whether another page of followers is available.
        next_page_token:
          type: string
          description: Token to pass back as next_page_token to retrieve the next page of followers.

    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong