> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keyapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Top AD search

> Search for popular ads on TikTok by keywords

<div className="inline-flex items-center gap-2 px-4 py-2 bg-yellow-50 dark:bg-yellow-900/20 border border-yellow-200 dark:border-yellow-800 rounded-lg">
  <span className="text-sm font-medium text-yellow-900 dark:text-yellow-100"><span className="font-semibold">2 credits</span><span className="text-yellow-700 dark:text-yellow-300 ml-1">per request</span></span>
</div>

## Copy for AI

<div className="my-6 rounded-xl border border-gray-200 bg-gray-50 p-5 dark:border-gray-800 dark:bg-gray-900/40">
  <div className="min-w-0">
    <p className="text-base font-semibold text-gray-900 dark:text-gray-100">Why Code When AI Can Do It For You?</p>
    <p className="mt-1 text-sm text-gray-700 dark:text-gray-300">Stop writing code like it's 1970! Let AI do the heavy lifting - click the button to copy a perfectly formatted prompt for ChatGPT, Claude, or your favorite AI assistant.</p>
  </div>

  <div className="mt-4">
    <button
      type="button"
      className="inline-flex items-center gap-2 rounded-md border border-emerald-300 bg-emerald-50 px-3 py-2 text-sm font-medium text-emerald-800 hover:bg-emerald-100 dark:border-emerald-700 dark:bg-emerald-900/30 dark:text-emerald-100 dark:hover:bg-emerald-900/50"
      onClick={() => navigator.clipboard.writeText(`I need to call the following KeyAPI endpoint. Please generate a complete and directly runnable Python example based on the API information provided below.

## API Information

Endpoint: GET https://api.keyapi.ai/v1/tk-ads/top_ads_search
Summary: Top AD search

Required Headers:
- Authorization: Bearer <YOUR_API_KEY>

Parameters:
- keyword (Required): No description. Example: KurkurePakistan
- page (Optional): Page Number
- limit (Optional): MaxPerPage
- country_code (Optional): Can be obtained from \`/v1/tk-ads/get_priority_region\`
- period (Optional): Available values: 7=Last 7 Days, 30=Last 30 Days, 180=Last 180 Days Example: 180
- order_by (Optional): Sort by, Available values: 
for_you = See relevant Top Ads that are selected for you based on your activity and business information.
impression = The total number of users who viewed the video at least once.
ctr = Click-through rate (CTR) is a ratio that shows the amount of viewers that clicked the ad to the total amount of viewers. It is calculated by dividing the number of clicks by the number of viewers.
play_2s_rate = The number of views that were 2 seconds or longer divided by the total number of video views.
play_6s_rate = The number of views that were 6 seconds or longer divided by the total number of video views.
cvr = Conversion rate (CVR) measure the percentage of conversions created (such as follows, downloads, or purchases) at every second in the video. It is calculated by dividing the number of conversions by the number of interactions
like = Likes
- industry (Optional): Industry ID,Select from the industry ID list. If omitted, no industry filter is applied and all industries are included.
- objective (Optional): Objective, If omitted, no campaign objective filter is applied and all objectives are included.Available values: 1=Traffic, 2=App Installs, 3=Conversions, 4=Video Views, 5=Reach, 8=Lead Generation, 15=Product Sales Example: 1,2,3,4
- ad_language (Optional): Ad Language, If omitted, no ad language filter is applied and all languages are included.
Available values: en, es, ar, vi, th, de, id, pt, fr, ms, nl, ja, it, ro, zh-Hant, ko Example: en,es,ar,vi,th
- ad_format (Optional): Ad Format, If omitted, no ad format filter is applied and all formats are included.
Available values: 1=Spark Ads, 2=Non-Spark Ads
- like (Optional): Likes, If omitted, no like count percentile filter is applied and all ranges are included.
Available values: 1=Top 1–20%, 2=Top 21–40%, 3=Top 41–60%, 4=Top 61–80%, 5=Top 81–100% Example: 1,2,3,4,5


## Code Requirements

- Use the Python \`requests\` library
- Provide a complete and directly runnable example
- Handle HTTP request errors, timeouts, and non-2xx responses
- Handle JSON parsing errors
- Prefer the Example values provided in the API information for sample parameters
- Keep the code simple and avoid unnecessary abstractions or complexity
`)}
    >
      <span>Copy for AI</span>
    </button>
  </div>
</div>


## OpenAPI

````yaml en/tiktok-ads-library.openapi.json GET /v1/tk-ads/top_ads_search
openapi: 3.0.1
info:
  title: Tiktok-ads API english documentation
  description: >-
    The english reference documentation of the Tiktok-ads API includes the
    interface's purpose, parameter description, response status, and sample
    structure.
  version: 1.0.0
servers:
  - url: https://api.keyapi.ai
    description: Production-KeyAPI
security: []
tags: []
paths:
  /v1/tk-ads/top_ads_search:
    get:
      tags: []
      summary: Top AD search
      description: Search for popular ads on TikTok by keywords
      parameters:
        - name: keyword
          in: query
          description: ''
          required: true
          example: KurkurePakistan
          schema:
            type: string
            example: KurkurePakistan
        - name: page
          in: query
          description: Page Number
          required: false
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: MaxPerPage
          required: false
          schema:
            type: integer
            default: 20
            maximum: 20
            minimum: 1
        - name: country_code
          in: query
          description: >-
            If omitted, all countries are included. Available values can be
            obtained from `/v1/tk-ads/get_priority_region`
          required: false
          schema:
            type: string
            example: US,JP,AR,AU
        - name: period
          in: query
          description: 'Available values: 7=Last 7 Days, 30=Last 30 Days, 180=Last 180 Days'
          required: false
          example: 180
          schema:
            type: integer
            enum:
              - 7
              - 30
              - 180
            default: 30
        - name: order_by
          in: query
          description: >-
            Sort by, Available values: 

            for_you = See relevant Top Ads that are selected for you based on
            your activity and business information.

            impression = The total number of users who viewed the video at least
            once.
             ctr = Click-through rate (CTR) is a ratio that shows the amount of viewers that clicked the ad to the total amount of viewers. It is calculated by dividing the number of clicks by the number of viewers.
            play_2s_rate = The number of views that were 2 seconds or longer
            divided by the total number of video views.

            play_6s_rate = The number of views that were 6 seconds or longer
            divided by the total number of video views.

            cvr = Conversion rate (CVR) measure the percentage of conversions
            created (such as follows, downloads, or purchases) at every second
            in the video. It is calculated by dividing the number of conversions
            by the number of interactions

            like = Likes
          required: false
          example: ''
          schema:
            type: string
            enum:
              - for_you
              - impression
              - ctr
              - play_2s_rate
              - play_6s_rate
              - cvr
              - like
            default: for_you
        - name: industry
          in: query
          description: >-
            Industry ID,Select from the industry ID list. If omitted, no
            industry filter is applied and all industries are included.
          required: false
          schema:
            type: string
        - name: objective
          in: query
          description: >-
            Objective, If omitted, no campaign objective filter is applied and
            all objectives are included.Available values: 1=Traffic, 2=App
            Installs, 3=Conversions, 4=Video Views, 5=Reach, 8=Lead Generation,
            15=Product Sales
          required: false
          schema:
            type: string
            example: 1,2,3,4
        - name: ad_language
          in: query
          description: >-
            Ad Language, If omitted, no ad language filter is applied and all
            languages are included.

            Available values: en, es, ar, vi, th, de, id, pt, fr, ms, nl, ja,
            it, ro, zh-Hant, ko
          required: false
          schema:
            type: string
            example: en,es,ar,vi,th
        - name: ad_format
          in: query
          description: >-
            Ad Format, If omitted, no ad format filter is applied and all
            formats are included.

            Available values: 1=Spark Ads, 2=Non-Spark Ads
          required: false
          schema:
            type: string
        - name: like
          in: query
          description: >-
            Likes, If omitted, no like count percentile filter is applied and
            all ranges are included.

            Available values: 1=Top 1–20%, 2=Top 21–40%, 3=Top 41–60%, 4=Top
            61–80%, 5=Top 81–100%
          required: false
          schema:
            type: string
            example: 1,2,3,4,5
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties: {}
              example:
                code: 0
                message: success
                data:
                  materials:
                    - ad_title: >-
                        Masalaydaar Tarkay, Karak Krunch Kar Ke - Sab Hogaye
                        KrazyForKurkure!
                      brand_name: KurkurePakistan
                      cost: 2
                      ctr: 0.38
                      favorite: false
                      id: '7552078920880619527'
                      industry_key: label_27101000000
                      is_search: false
                      like: 2152849
                      objective_key: campaign_objective_reach
                      video_info:
                        vid: v14033g50000d93a40fog65sgujaemn0
                        duration: 15.019
                        cover: >-
                          https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/oYmEEquhABAgo65E41i8Am1A5BnwWA8IIafCGi~tplv-noop.image?dr=18692&refresh_token=3e3ac8cf&x-expires=1789393503&x-signature=n9fUX0u9Z5ItPNTWoXQRuRHJ14A%3D&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=317596d8&idc=my&VideoID=v14033g50000d93a40fog65sgujaemn0
                        video_url:
                          1080p: >-
                            https://v16m-default.tiktokcdn.com/955090cb9c916a426c59a5a157e6e43c/6aa7fa5f/video/tos/alisg/tos-alisg-ve-0051c001-sg/oo7fIaCTDAyExHb1GII1eQ6AD1yGhLe42gIt2G/?a=0&bti=NTU4QDM1NGA%3D&&bt=3699&ft=cApXJCz7ThWH3DpDLGZmo0P&mime_type=video_mp4&rc=aGk1PDk3PDY6Mzk3M2c7NEBpM3BkeHY5cjNkPDMzODYzNEAuNDAyNjQ2XmExMzAvM2NhYSNrYmdkMmRjMTBhLS1kMDFzcw%3D%3D&vvpl=1&l=20260914154448470D7C13C73CB14AF8F7&btag=e000b8000
                          360p: >-
                            https://v16m-default.tiktokcdn.com/f81fd15c963706418668a20979389fea/6aa7fa5f/video/tos/alisg/tos-alisg-ve-0051c001-sg/ogABII22TDKzt61eAGCzvuKhLQ4IgEeb0Gf7D1/?a=0&bti=NTU4QDM1NGA%3D&&bt=637&ft=cApXJCz7ThWH3DpDLGZmo0P&mime_type=video_mp4&rc=NTg6NDdoZjNpM2c5ZWY1NEBpM3BkeHY5cjNkPDMzODYzNEBeXi1jMWJeNjIxYi5eNGMzYSNrYmdkMmRjMTBhLS1kMDFzcw%3D%3D&vvpl=1&l=20260914154448470D7C13C73CB14AF8F7&btag=e000b8000
                          480p: >-
                            https://v16m-default.tiktokcdn.com/13f109c2dfb52078173aeaaf9c9c85d5/6aa7fa5f/video/tos/alisg/tos-alisg-ve-0051c001-sg/o8BRQe6fGDHTLu2G1DIt25I0hCgE71IAexbP4A/?a=0&bti=NTU4QDM1NGA%3D&&bt=938&ft=cApXJCz7ThWH3DpDLGZmo0P&mime_type=video_mp4&rc=ZTY8aGc2OWRlN2c1ODZoNEBpM3BkeHY5cjNkPDMzODYzNEAvYi4tLWNiNmExLV9hYjY1YSNrYmdkMmRjMTBhLS1kMDFzcw%3D%3D&vvpl=1&l=20260914154448470D7C13C73CB14AF8F7&btag=e000b8000
                          540p: >-
                            https://v16m-default.tiktokcdn.com/00d0d1bf5360cb7555b4e373199406dc/6aa7fa5f/video/tos/alisg/tos-alisg-ve-0051c001-sg/oUEGThQe2212GC17qv4DpIWAI3g0D6CIfAeLbt/?a=0&bti=NTU4QDM1NGA%3D&&bt=1285&ft=cApXJCz7ThWH3DpDLGZmo0P&mime_type=video_mp4&rc=PDxpZzU4aWVoZWg4Omg0N0BpM3BkeHY5cjNkPDMzODYzNEAxLzFgLTYxNmAxLzNjMTAzYSNrYmdkMmRjMTBhLS1kMDFzcw%3D%3D&vvpl=1&l=20260914154448470D7C13C73CB14AF8F7&btag=e000b8000
                          720p: >-
                            https://v16m-default.tiktokcdn.com/822724f69c9d4e45b6faa141e0833297/6aa7fa5f/video/tos/alisg/tos-alisg-ve-0051c001-sg/oEbbPD12AeZE6Q0T12gLI4IhICfe8D0D3AGtG7/?a=0&bti=NTU4QDM1NGA%3D&&bt=1852&ft=cApXJCz7ThWH3DpDLGZmo0P&mime_type=video_mp4&rc=ZDVkZTk7Zzg3aTo5ZWVpZEBpM3BkeHY5cjNkPDMzODYzNEBfNC4uNDU1NTYxYWMuLy1jYSNrYmdkMmRjMTBhLS1kMDFzcw%3D%3D&vvpl=1&l=20260914154448470D7C13C73CB14AF8F7&btag=e000b8000
                        width: 720
                        height: 1280
                  pagination:
                    has_more: false
                    page: 1
                    size: 20
                    total_count: 1
                requestId: 0af59e6a-2544-45c3-898f-36b6b4985107
          headers: {}
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      deprecated: false
      security:
        - JWT Bearer: []
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl --request GET \
              --url 'https://api.keyapi.ai/v1/tk-ads/top_ads_search?keyword=KurkurePakistan&page=1&limit=20&period=180&objective=1%2C2%2C3%2C4&ad_language=en%2Ces%2Car%2Cvi%2Cth&like=1%2C2%2C3%2C4%2C5' \
              --header 'Authorization: Bearer <YOUR_API_KEY>'
        - lang: python
          label: Python
          source: |-
            import requests

            response = requests.get(
                'https://api.keyapi.ai/v1/tk-ads/top_ads_search',
                params={"keyword":"KurkurePakistan","page":1,"limit":20,"period":180,"objective":"1,2,3,4","ad_language":"en,es,ar,vi,th","like":"1,2,3,4,5"},
                headers={'Authorization': 'Bearer <YOUR_API_KEY>'}
            )
            print(response.json())
        - lang: javascript
          label: JavaScript
          source: >-
            const params = new
            URLSearchParams({"keyword":"KurkurePakistan","page":1,"limit":20,"period":180,"objective":"1,2,3,4","ad_language":"en,es,ar,vi,th","like":"1,2,3,4,5"});


            const response = await
            fetch(`https://api.keyapi.ai/v1/tk-ads/top_ads_search?${params}`, {
              method: 'GET',
              headers: { 'Authorization': 'Bearer <YOUR_API_KEY>' }
            });

            const data = await response.json();

            console.log(data);
components:
  responses:
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            example:
              code: 400
              data: null
              message: 'Missing required parameter: handle'
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            example:
              code: 401
              data: null
              message: apiKey is null
    '402':
      description: Payment Required
      content:
        application/json:
          schema:
            type: object
            example:
              code: 402
              data: null
              message: apiKey quota is not enough
    '429':
      description: Too Many Requests
      content:
        application/json:
          schema:
            type: object
            example:
              code: 429
              data: null
              message: qps limit exceeded
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            example:
              code: 500
              data: null
              message: Internal server error
  securitySchemes:
    JWT Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |-
        API key for authentication. Format: `sk_live_xxxxxxxxxxxxx`
        Get your API key from the [Dashboard](http://keyapi.ai/app/dashboard).

````