openapi: 3.0.0
info:
  title: TikTok Explore API
  description: |
    Retrieve the videos TikTok is currently surfacing on its Explore page, for all of TikTok or for one of
    its 20 topic categories. Each country has its own Explore feed: set country to read another market's
    (by default, the United States). Each video includes its caption, publish time, duration, thumbnail,
    engagement counts, the sound it uses, the hashtags and mentions parsed from the caption, and usually its
    creator.
    TikTok rounds view, like, comment and share counts once they reach 10,000; save counts are exact. Each
    request returns one batch of up to 30 videos.

    **Cross-linking**: pass a video's link as url to the TikTok Video and TikTok Transcripts APIs, and its
    author.username to the TikTok Profile and TikTok Profile Videos APIs. TikTok occasionally returns a batch
    without creator details; those videos have no author or link.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: TikTok Explore Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine identifier
          schema:
            type: string
            enum: ["tiktok_explore"]
            default: "tiktok_explore"
        - name: category
          in: query
          required: false
          description: Explore category to read
          schema:
            type: string
            enum: ["all", "singing_dancing", "comedy", "sports", "anime_comics", "relationship", "shows", "lipsync", "daily_life", "beauty_care", "games", "society", "outfit", "cars", "food", "animals", "family", "drama", "fitness_health", "education", "technology"]
            default: "all"
        - name: country
          in: query
          required: false
          description: Two-letter country code whose Explore feed to return
          schema:
            type: string
            default: "US"
            enum: ["US", "GB", "CA", "AU", "NZ", "IE", "DE", "FR", "ES", "IT", "PT", "NL", "BE", "AT", "CH", "SE", "NO", "DK", "FI", "PL", "CZ", "RO", "HU", "GR", "TR", "IL", "AE", "SA", "EG", "MA", "BR", "MX", "AR", "CO", "CL", "PE", "JP", "KR", "TW", "PH", "ID", "TH", "VN", "MY", "SG", "PK", "BD", "NG", "ZA", "KE", "UA", "KZ"]
        - name: num
          in: query
          required: false
          description: Maximum number of videos to return
          schema:
            type: integer
            minimum: 1
            maximum: 30
            default: 16
      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, videos]
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        videos:
          type: array
          description: Videos in the feed, in the order TikTok surfaces them
          items:
            $ref: '#/components/schemas/Video'
        error:
          type: string
          description: Error message when no results are found

    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
      required: [engine, category, country]
      properties:
        engine:
          type: string
          description: Search engine identifier
        category:
          type: string
          description: Explore category read for this request
        country:
          type: string
          description: Country whose Explore feed was read
        num:
          type: string
          description: Maximum number of videos requested

    Video:
      type: object
      required: [position, id, type, iso_date, thumbnail, views, likes, comments, shares, saves]
      properties:
        position:
          type: integer
          description: 1-based position of the video in the feed
        id:
          type: string
          description: TikTok video ID
        link:
          type: string
          description: Canonical URL of the video or photo post
        type:
          type: string
          enum: ["video", "photo", "carousel"]
          description: Post type
        title:
          type: string
          description: Title of a photo post
        caption:
          type: string
          description: Post caption
        language:
          type: string
          description: Caption language code
        hashtags:
          type: array
          description: Hashtags parsed from the caption
          items:
            type: string
        mentions:
          type: array
          description: Usernames mentioned in the caption
          items:
            type: string
        iso_date:
          type: string
          format: date-time
          description: Publish time in ISO 8601 format
        duration:
          type: integer
          description: Video duration in seconds
        width:
          type: integer
          description: Video width in pixels
        height:
          type: integer
          description: Video height in pixels
        is_pinned:
          type: boolean
          description: Whether the video is pinned to the top of its creator's profile
        is_ad:
          type: boolean
          description: Whether the video is a sponsored post
        is_duet_enabled:
          type: boolean
          description: Whether duets are allowed on the video
        is_stitch_enabled:
          type: boolean
          description: Whether stitches are allowed on the video
        views:
          type: integer
          description: Number of views, rounded by TikTok once it reaches 10,000
        likes:
          type: integer
          description: Number of likes, rounded by TikTok once it reaches 10,000
        comments:
          type: integer
          description: Number of comments, rounded by TikTok once it reaches 10,000
        shares:
          type: integer
          description: Number of shares, rounded by TikTok once it reaches 10,000
        saves:
          type: integer
          description: Number of saves
        thumbnail:
          type: string
          description: Cover image URL, signed by TikTok and valid for about 48 hours
        dynamic_thumbnail:
          type: string
          description: Animated cover image URL, signed by TikTok and valid for about 48 hours
        carousel_items:
          type: array
          description: Slides of a photo carousel
          items:
            $ref: '#/components/schemas/CarouselItem'
        video_meta:
          $ref: '#/components/schemas/VideoMeta'
        music:
          $ref: '#/components/schemas/Music'
        location:
          $ref: '#/components/schemas/Location'
        subtitles:
          type: array
          description: Closed captions available for the video
          items:
            $ref: '#/components/schemas/Subtitle'
        author:
          $ref: '#/components/schemas/Author'

    Author:
      type: object
      description: The creator who posted the video
      required: [id, sec_uid, username, link, name, avatar]
      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 of the creator's profile
        name:
          type: string
          description: Display name
        bio:
          type: string
          description: Profile bio
        avatar:
          type: string
          description: Avatar image URL, signed by TikTok and valid for about 48 hours
        avatar_hd:
          type: string
          description: High-resolution avatar image URL, signed by TikTok and valid for about 48 hours
        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 the creator follows
        hearts:
          type: integer
          description: Total likes received across all posts
        posts:
          type: integer
          description: Total number of posts
        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

    VideoMeta:
      type: object
      description: Video quality and encoding metadata
      properties:
        definition:
          type: string
          description: Playback definition label
        ratio:
          type: string
          description: Quality ratio label
        format:
          type: string
          description: Container format
        codec_type:
          type: string
          description: Video codec
        size:
          type: integer
          description: Encoded size in bytes of the default rendition
        bitrate:
          type: integer
          description: Bitrate in bits per second of the default rendition
        bitrates:
          type: array
          description: Per-codec encoding variants
          items:
            $ref: '#/components/schemas/Bitrate'

    Bitrate:
      type: object
      properties:
        gear_name:
          type: string
          description: Rendition name
        bitrate:
          type: integer
          description: Bitrate in bits per second
        fps:
          type: integer
          description: Frames per second
        codec_type:
          type: string
          description: Video codec
        format:
          type: string
          description: Container format

    Subtitle:
      type: object
      properties:
        language:
          type: string
          description: Caption language code
        format:
          type: string
          description: Caption file format
        source:
          type: string
          description: How the caption was produced
        url:
          type: string
          description: Caption file URL, signed by TikTok
        url_expires_at:
          type: string
          format: date-time
          description: UTC ISO 8601 timestamp when the caption URL expires

    CarouselItem:
      type: object
      properties:
        position:
          type: integer
          description: 1-based slide position
        image:
          type: string
          description: Full-resolution slide image URL
        width:
          type: integer
          description: Slide image width in pixels
        height:
          type: integer
          description: Slide image height in pixels

    Location:
      type: object
      description: Venue tagged on the post
      properties:
        id:
          type: string
          description: TikTok place ID
        name:
          type: string
          description: Venue name
        address:
          type: string
          description: Street address
        city:
          type: string
          description: City
        category:
          type: string
          description: Venue category

    Music:
      type: object
      description: The sound used by the post
      properties:
        id:
          type: string
          description: TikTok sound ID
        title:
          type: string
          description: Sound title
        album:
          type: string
          description: Album the sound belongs to
        author:
          type: string
          description: Sound author name
        cover:
          type: string
          description: Sound cover art URL, signed by TikTok and valid for about 48 hours
        duration:
          type: integer
          description: Sound duration in seconds
        play_url:
          type: string
          description: Direct audio stream URL, signed by TikTok
        is_original:
          type: boolean
          description: Whether the sound is an original creation
        is_copyrighted:
          type: boolean
          description: Whether the sound is copyrighted
        link:
          type: string
          description: URL of the sound's TikTok page

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