openapi: 3.0.0
info:
  title: TikTok Profile Live API
  description: |
    Check whether a TikTok creator is live right now. Every account TikTok finds comes with the creator's profile and an is_live flag; while the creator is on air it also carries the live room: title, cover image, viewer counts and start time.

    **Cross-linking**: The `username` is the same handle the TikTok Profile and TikTok Profile Videos APIs accept, so a creator found through the TikTok Search API (`profiles.*.username`) can be checked for a live stream here.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: TikTok Profile Live Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine identifier
          schema:
            type: string
            enum: ["tiktok_profile_live"]
            default: "tiktok_profile_live"
        - name: username
          in: query
          required: true
          description: TikTok username of the creator to check, with or without the leading @
          schema:
            type: string
            pattern: '^@?[a-zA-Z0-9_.]{1,24}$'
      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
      required: [search_metadata, search_parameters]
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        profile:
          $ref: '#/components/schemas/Profile'
        is_live:
          type: boolean
          description: Whether the creator is streaming live at the time of the request.
        live:
          $ref: '#/components/schemas/Live'
        error:
          type: string
          description: Error message for a username with no TikTok account behind it, or an account TikTok shows only to signed-in viewers.

    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

    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: Number of followers.
        following:
          type: integer
          description: Number of accounts this profile follows.

    Live:
      type: object
      properties:
        room_id:
          type: string
          description: Identifier of the live room.
        link:
          type: string
          description: URL of the creator's LIVE page.
        title:
          type: string
          description: Title of the live stream.
        cover:
          type: string
          description: URL of the stream's cover image.
        viewers:
          type: integer
          description: Number of people watching at the time of the request.
        total_viewers:
          type: integer
          description: Cumulative number of room entries since the stream started, which may count a viewer who rejoins more than once.
        started_at:
          type: string
          format: date-time
          description: Stream start timestamp in ISO 8601 format.

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