openapi: 3.0.0
info:
  title: TikTok Profile Following API
  description: |
    Retrieve the accounts a TikTok user follows, by username. The response carries a profile summary
    and a page of up to 30 followed accounts, each with its username, display name, bio, avatar,
    verification and privacy flags, and follower, following, hearts and posts counts.

    **Cross-linking**: The username comes from the TikTok Profile or TikTok Search API. Pass a followed
    account's username to the TikTok Profile API for its full profile, or to the TikTok Profile Videos
    API to retrieve its video feed.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: TikTok Profile Following Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine identifier
          schema:
            type: string
            enum: ["tiktok_profile_following"]
            default: "tiktok_profile_following"
        - 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 followed accounts, returned as pagination.next_page_token when pagination.has_more is true
          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'
        following:
          type: array
          description: The page of accounts the user follows
          items:
            $ref: '#/components/schemas/FollowedAccount'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Error message for a username that does not exist, an account whose following list is private, a user who follows no accounts, a profile that requires login to view, or a page past the accounts 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 or description
        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: Number of followers
        following:
          type: integer
          description: Number of accounts being followed
        hearts:
          type: integer
          description: Total hearts (likes) received across all videos
        posts:
          type: integer
          description: Total number of videos posted

    FollowedAccount:
      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 account in the returned page
        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 account's profile page
        name:
          type: string
          description: Display name
        bio:
          type: string
          description: Profile bio or description
        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: Number of followers
        following:
          type: integer
          description: Number of accounts being followed
        hearts:
          type: integer
          description: Total hearts (likes) received across all videos
        posts:
          type: integer
          description: Total number of videos 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 followed accounts is available
        next_page_token:
          type: string
          description: Token to pass back as next_page_token to retrieve the next page of followed accounts

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