openapi: 3.0.0
info:
  title: TikTok Ads Library Ad Details API
  description: |
    The TikTok Ads Library Ad Details API returns structured details for a single ad
    in the TikTok Ads Library. Given an `ad_id`, it returns creative assets (video
    and cover image), advertiser details, targeting (location, age, gender), audience
    size estimates, and impression data.

    **Usage:** Obtain `ad_id` values from the TikTok Ads Library API (`engine=tiktok_ads_library`)
    response. Each ad in that response includes an `id` field usable here.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: TikTok Ads Library Ad Details Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Must be set to `tiktok_ads_library_ad_details`
          schema:
            type: string
            enum: ["tiktok_ads_library_ad_details"]
        - name: ad_id
          in: query
          required: true
          description: Unique identifier of the TikTok ad, from the TikTok Ads Library API 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
      description: |
        Either `ad` is returned (ad found) or `error` is returned
        (e.g. ad_id does not exist or TikTok returned no data).
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        ad:
          $ref: '#/components/schemas/Ad'
        error:
          type: string
          description: Present when TikTok returns no ad for the given ad_id.
    SearchMetadata:
      type: object
      required: [id, status, created_at]
      properties:
        id:
          type: string
        status:
          type: string
        created_at:
          type: string
          format: date-time
        request_time_taken:
          type: number
        parsing_time_taken:
          type: number
        total_time_taken:
          type: number
        request_url:
          type: string
          description: Public TikTok Ads Library URL for this ad
        html_url:
          type: string
        json_url:
          type: string
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
        ad_id:
          type: string
    Ad:
      type: object
      required:
        - id
        - advertiser
        - first_shown_datetime
        - last_shown_datetime
        - video_link
        - cover_image
        - estimated_audience
        - targeting
      properties:
        id:
          type: string
          description: Unique identifier of the ad
        advertiser:
          $ref: '#/components/schemas/Advertiser'
        is_unavailable:
          type: boolean
          description: True when TikTok has flagged the ad as unavailable
        first_shown_datetime:
          type: string
          format: date-time
        last_shown_datetime:
          type: string
          format: date-time
        video_link:
          type: string
        cover_image:
          type: string
        image_urls:
          type: array
          items:
            type: string
        estimated_audience:
          type: string
          description: Raw audience-size range from TikTok (e.g. "0-1K")
        estimated_audience_min:
          type: integer
          description: Parsed lower bound of estimated_audience. Omitted when the raw value is not a range.
        estimated_audience_max:
          type: integer
          description: Parsed upper bound of estimated_audience. Omitted when the raw value is not a range.
        spent:
          type: string
        impression:
          type: integer
        rejection_info:
          type: string
          nullable: true
        targeting:
          $ref: '#/components/schemas/Targeting'
    Advertiser:
      type: object
      required: [id, name]
      properties:
        id:
          type: string
          description: TikTok advertiser ID (adv_biz_ids)
        name:
          type: string
        registry_location:
          type: string
        tiktok_user:
          type: string
          nullable: true
        sponsor:
          type: string
    Targeting:
      type: object
      properties:
        location:
          $ref: '#/components/schemas/TargetingLocation'
        age:
          type: array
          items:
            $ref: '#/components/schemas/TargetingAgeBreakdown'
        gender:
          type: array
          items:
            $ref: '#/components/schemas/TargetingGenderBreakdown'
        target_audience_size:
          type: string
          description: Raw audience-size range from TikTok (e.g. "24.8M-30.3M")
        target_audience_size_min:
          type: integer
          description: Parsed lower bound of target_audience_size. Omitted when the raw value is not a range.
        target_audience_size_max:
          type: integer
          description: Parsed upper bound of target_audience_size. Omitted when the raw value is not a range.
        audience_list:
          type: string
        interest:
          type: string
        video_interactions:
          type: string
        creator_interactions:
          type: string
    TargetingAgeBreakdown:
      type: object
      required: [region]
      description: |
        Per-region age-bucket exposure flags. Each boolean is true when the ad
        was shown to users in that age bucket in the given region.
      properties:
        region:
          type: string
          description: ISO country code (e.g. "GB")
        "13-17":
          type: boolean
        "18-24":
          type: boolean
        "25-34":
          type: boolean
        "35-44":
          type: boolean
        "45-54":
          type: boolean
        "55+":
          type: boolean
    TargetingGenderBreakdown:
      type: object
      required: [region]
      description: Per-region gender exposure flags.
      properties:
        region:
          type: string
          description: ISO country code (e.g. "GB")
        female:
          type: boolean
        male:
          type: boolean
        unknown:
          type: boolean
    TargetingLocation:
      type: object
      properties:
        total_region:
          type: integer
        total_impressions:
          type: string
        impressions_by_region:
          type: array
          items:
            type: object
            properties:
              region:
                type: string
              impressions:
                type: string
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong