> ## 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.

# Get top ads detail

> Ad Information(Region、Objective、Industry、Brand name、Landing Page、Ad caption、Ad performance)

<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_detail
Summary: Get top ads detail

Required Headers:
- Authorization: Bearer <YOUR_API_KEY>

Parameters:
- material_id (Required): Material ID,Can be obtained from \`/v1/tk-ads/top_ad_list\`, or from the TikTok Creative Center URL, e.g. \`https://ads.tiktok.com/business/creativecenter/topads/7469861356595134480/pc/zh?from=001110&period=180\`, where \`material_id = 7469861356595134480\`. Example: 7552078920880619527


## 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_detail
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_detail:
    get:
      tags: []
      summary: Get top ads detail
      description: >-
        Ad Information(Region、Objective、Industry、Brand name、Landing Page、Ad
        caption、Ad performance)
      parameters:
        - name: material_id
          in: query
          description: >-
            Material ID,Can be obtained from `/v1/tk-ads/top_ad_list`, or from
            the TikTok Creative Center URL, e.g.
            `https://ads.tiktok.com/business/creativecenter/topads/7469861356595134480/pc/zh?from=001110&period=180`,
            where `material_id = 7469861356595134480`.
          required: true
          example: '7552078920880619527'
          schema:
            type: string
            example: '7552078920880619527'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      country_code:
                        type: array
                        items:
                          type: string
                      objectives:
                        type: array
                        items:
                          type: string
                        description: objectives
                      industry_key:
                        type: string
                        description: Industry
                      ad_title:
                        type: string
                        description: Ad Title
                      brand_name:
                        type: string
                        description: Brand Name
                      landing_page:
                        type: string
                      highlight_text:
                        type: string
                        description: Highlight Text
                      comment:
                        type: integer
                        description: Number of comments
                      share:
                        type: integer
                        description: Share
                      ctr:
                        type: number
                        description: >-
                          Click-through rate (CTR) measures the percentage of
                          viewers who clicked the ad while watching at every
                          second. It is calculated by dividing the number of
                          clicks by the number of views.
                      cost:
                        type: integer
                        description: 预算，2=高预算
                      like:
                        type: integer
                        description: Number of likes
                      source:
                        type: string
                        description: Source
                    required:
                      - ad_title
                      - comment
                      - share
                      - ctr
                      - cost
                      - country_code
                      - objectives
                      - industry_key
                      - like
                      - landing_page
                      - source
                      - highlight_text
                required:
                  - code
                  - message
                  - data
              example:
                code: 0
                message: success
                data:
                  ad_title: >-
                    Masalaydaar Tarkay, Karak Krunch Kar Ke - Sab Hogaye
                    KrazyForKurkure!
                  brand_name: KurkurePakistan
                  comment: 11752
                  cost: 2
                  country_code:
                    - PK
                  ctr: 0.38
                  favorite: false
                  has_summary: false
                  highlight_text: ''
                  id: '7552078920880619527'
                  industry_key: label_27101000000
                  is_search: false
                  keyword_list: null
                  landing_page: >-
                    https://www.foodpanda.pk/darkstore/r1vf/pandamart-bahadurabad-khi/campaign/banner-69c51812c6d43c12bf5d9826?utm_campaign=coop_coop_web_dma_aut_aa_FP_PK_Kurkure&utm_medium=coops&utm_source=tiktok&utm_id=__CAMPAIGN_ID__
                  like: 2152849
                  objective_key: campaign_objective_reach
                  objectives:
                    - label: campaign_objective_reach
                      value: 5
                  pattern_label: []
                  share: 3181
                  source: TikTok Ads Manager
                  source_key: 1
                  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=4602ec8a&x-expires=1789389896&x-signature=7HDPZtA1WyKzn5Wc6yrG0WHTTfc%3D&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=317596d8&idc=my&VideoID=v14033g50000d93a40fog65sgujaemn0
                    video_url:
                      1080p: >-
                        https://v16m-default.tiktokcdn.com/875a8f276d9aaa989cc277d715761d93/6aa7ec48/video/tos/alisg/tos-alisg-ve-0051c001-sg/oo7fIaCTDAyExHb1GII1eQ6AD1yGhLe42gIt2G/?a=0&bti=NTU4QDM1NGA%3D&&bt=3699&ft=cApXJCz7ThWHG7qDLGZmo0P&mime_type=video_mp4&rc=aGk1PDk3PDY6Mzk3M2c7NEBpM3BkeHY5cjNkPDMzODYzNEAuNDAyNjQ2XmExMzAvM2NhYSNrYmdkMmRjMTBhLS1kMDFzcw%3D%3D&vvpl=1&l=20260914144441B141D3E23966E171E9DC&btag=e000b8000
                      360p: >-
                        https://v16m-default.tiktokcdn.com/fb2b778a3e00c07daa1c66a62336a01f/6aa7ec48/video/tos/alisg/tos-alisg-ve-0051c001-sg/ogABII22TDKzt61eAGCzvuKhLQ4IgEeb0Gf7D1/?a=0&bti=NTU4QDM1NGA%3D&&bt=637&ft=cApXJCz7ThWHG7qDLGZmo0P&mime_type=video_mp4&rc=NTg6NDdoZjNpM2c5ZWY1NEBpM3BkeHY5cjNkPDMzODYzNEBeXi1jMWJeNjIxYi5eNGMzYSNrYmdkMmRjMTBhLS1kMDFzcw%3D%3D&vvpl=1&l=20260914144441B141D3E23966E171E9DC&btag=e000b8000
                      480p: >-
                        https://v16m-default.tiktokcdn.com/ed6034a1a70ddc85c926d864783a5335/6aa7ec48/video/tos/alisg/tos-alisg-ve-0051c001-sg/o8BRQe6fGDHTLu2G1DIt25I0hCgE71IAexbP4A/?a=0&bti=NTU4QDM1NGA%3D&&bt=938&ft=cApXJCz7ThWHG7qDLGZmo0P&mime_type=video_mp4&rc=ZTY8aGc2OWRlN2c1ODZoNEBpM3BkeHY5cjNkPDMzODYzNEAvYi4tLWNiNmExLV9hYjY1YSNrYmdkMmRjMTBhLS1kMDFzcw%3D%3D&vvpl=1&l=20260914144441B141D3E23966E171E9DC&btag=e000b8000
                      540p: >-
                        https://v16m-default.tiktokcdn.com/98f7c454750011c813c8341198877814/6aa7ec48/video/tos/alisg/tos-alisg-ve-0051c001-sg/oUEGThQe2212GC17qv4DpIWAI3g0D6CIfAeLbt/?a=0&bti=NTU4QDM1NGA%3D&&bt=1285&ft=cApXJCz7ThWHG7qDLGZmo0P&mime_type=video_mp4&rc=PDxpZzU4aWVoZWg4Omg0N0BpM3BkeHY5cjNkPDMzODYzNEAxLzFgLTYxNmAxLzNjMTAzYSNrYmdkMmRjMTBhLS1kMDFzcw%3D%3D&vvpl=1&l=20260914144441B141D3E23966E171E9DC&btag=e000b8000
                      720p: >-
                        https://v16m-default.tiktokcdn.com/30b69e12c23bc0259b512c23e24b8795/6aa7ec48/video/tos/alisg/tos-alisg-ve-0051c001-sg/oEbbPD12AeZE6Q0T12gLI4IhICfe8D0D3AGtG7/?a=0&bti=NTU4QDM1NGA%3D&&bt=1852&ft=cApXJCz7ThWHG7qDLGZmo0P&mime_type=video_mp4&rc=ZDVkZTk7Zzg3aTo5ZWVpZEBpM3BkeHY5cjNkPDMzODYzNEBfNC4uNDU1NTYxYWMuLy1jYSNrYmdkMmRjMTBhLS1kMDFzcw%3D%3D&vvpl=1&l=20260914144441B141D3E23966E171E9DC&btag=e000b8000
                    width: 720
                    height: 1280
                  voice_over: false
                requestId: 18ea5bb9-bf54-484b-830d-2d4ff85c45f8
          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_detail?material_id=7552078920880619527' \
              --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_detail',
                params={"material_id":"7552078920880619527"},
                headers={'Authorization': 'Bearer <YOUR_API_KEY>'}
            )
            print(response.json())
        - lang: javascript
          label: JavaScript
          source: >-
            const params = new
            URLSearchParams({"material_id":"7552078920880619527"});


            const response = await
            fetch(`https://api.keyapi.ai/v1/tk-ads/top_ads_detail?${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).

````