---
title: "Ads › Top"
method: GET
path: "/v1/tiktok/ads/top"
tags: ["tiktok"]
---

# Ads › Top

`GET /v1/tiktok/ads/top`

## Request

- Base URL: `https://api.insightsocial.app`
- URL: `https://api.insightsocial.app/v1/tiktok/ads/top`
- Auth: API key in header `x-api-key`

Returns TikTok's Creative Center leaderboard of top-performing ads for a market and time window, each with click-through rate, board rank, like count, industry, objective, and the ad video.

Use it to find ad creative that actually performed. It is one window with no cursor, so set limit for depth and change country, period, or order_by for a different board.

**Metered: 100–1000 credits.** We reserve the ceiling when the call starts and charge what it actually used when it finishes.

## Query parameters

- `country` 'US' | 'CA' | 'MX' | 'BR' | 'GB' | 'DE' | 'FR' | 'IT' | 'ES' | 'NL' | 'PL' | 'SE' | 'TR' | 'SA' | 'AE' | 'AU' | 'JP' | 'KR' | 'ID' | 'TH' | 'VN' | 'MY' | 'PH' | 'SG'
- `period` '7' | '30' | '180'
- `order_by` 'for_you' | 'impression' | 'ctr' | 'play_2s_rate' | 'play_6s_rate' | 'cvr' | 'like'
- `ad_format` 'All ad types' | 'Spark ads' | 'Non-Spark ads'
- `ad_language` 'en' | 'ja' | 'zh' | 'vi' | 'th' | 'pt' | 'id'
- `like_tier` '1' | '2' | '3' | '4' | '5'
- `industry` string
- `keyword` string
- `limit` integer
- `since` string
- `until` string
- `dry_run` '1'

## Response `200`

Success.

- object
  - `success` true, required
  - `platform` string, required
  - `endpoint` string, required
  - `schema_version` '2', required
  - `data` PostPage, required
    - `items` object[], required
      - `post` Post, required
        - `id` string, required: An identifier, always a string. Never parse it as a number: several platforms use ids above 2^53.
        - `url` string, uri, nullable, required
        - `kind` string, nullable, required: The format of the post. Format words only, never a platform name. short = short-form vertical video (a reel, a TikTok, a YouTube Short).
        - `content` object, required
          - `text` string, nullable, required
          - `media_urls` string[], nullable, required
          - `thumbnail_url` string, uri, nullable, required
          - `duration_seconds` number, nullable, required
        - `author` Author, required
          - `id` string, nullable, required: An identifier, always a string. Never parse it as a number: several platforms use ids above 2^53.
          - `username` string, nullable, required
          - `display_name` string, nullable, required
          - `avatar_url` string, uri, nullable, required
          - `verified` boolean, nullable, required
        - `engagement` object, required
          - `views` integer, nullable, required: A count. null when the platform does not expose it; 0 only when it is really zero.
          - `likes` integer, nullable, required: A count. null when the platform does not expose it; 0 only when it is really zero.
          - `comments` integer, nullable, required: A count. null when the platform does not expose it; 0 only when it is really zero.
          - `shares` integer, nullable, required: A count. null when the platform does not expose it; 0 only when it is really zero.
          - `saves` integer, nullable, required: A count. null when the platform does not expose it; 0 only when it is really zero.
        - `flags` object, required
          - `nsfw` boolean, nullable, required
          - `spoiler` boolean, nullable, required
          - `pinned` boolean, nullable, required
          - `deleted` boolean, required
          - `likes_hidden` boolean, nullable, required
          - `comments_hidden` boolean, nullable, required
          - `shares_hidden` boolean, nullable, required
          - `views_hidden` boolean, nullable, required
          - `saves_hidden` boolean, nullable, required
        - `published_at` string, date-time, nullable, required: ISO-8601 timestamp in UTC, ending in Z.
        - `language` string, nullable, required: The content's language as the platform states it, e.g. en, pt-BR. Detected languages come later (§7.1).
        - `ext` object, nullable, required: Platform-specific fields, snake_case. The key list per platform is in the docs.
    - `total` integer, nullable, required: A count. null when the platform does not expose it; 0 only when it is really zero.
    - `truncated` boolean, nullable, required
    - `ext` object, nullable: Platform-specific fields, snake_case. The key list per platform is in the docs.
  - `pagination` Pagination
    - `next_cursor` string, nullable, required
    - `has_more` boolean, required
    - `page_size` integer, required
    - `stopped_at` 'since' | 'known_id' | 'end', nullable
  - `unavailable` string[], required
  - `credits_used` integer, required
  - `credits_remaining` integer, required
  - `request_id` string, required
  - `cached` boolean, required
  - `idempotent_replay` boolean, required
  - `charge_reason` string, required
  - `free_call` boolean, required

## Other responses

- `400`: See [Error handling](https://www.insightsocial.app/docs/errors).
- `401`: See [Error handling](https://www.insightsocial.app/docs/errors).
- `402`: See [Error handling](https://www.insightsocial.app/docs/errors).
- `404`: See [Error handling](https://www.insightsocial.app/docs/errors).
- `409`: See [Error handling](https://www.insightsocial.app/docs/errors).
- `429`: See [Error handling](https://www.insightsocial.app/docs/errors).
- `500`: See [Error handling](https://www.insightsocial.app/docs/errors).
- `503`: See [Error handling](https://www.insightsocial.app/docs/errors).

---

[API](https://skmtc.dev/insightsocial/apis/insightsocial-api.md) · [All operations](https://skmtc.dev/insightsocial/apis/insightsocial-api/llms.txt) · [OpenAPI document](https://skmtc.dev/insightsocial/apis/insightsocial-api/revisions/c82924cdabf2?raw)