# TikTok Top Ads API

TikTok Ad Library

Returns TikTok Creative Center's Top Ads board: the ads that performed best in a market over the last 7, 30 or 180 days. Each ad has its video, headline, brand, industry and campaign objective, with the board's rank, likes, click-through percentile and budget level. Narrow it by industry, objective or ad language, and rank it by Creative Center's own order or by impressions, likes, click-through, conversion or view-through rate. With no params you get the US board for the last 30 days. [Overview and pricing](https://socialtap.dev/apis/tiktok/top-ads/index.md)

GET `/v1/tiktok/top_ads`

## Example

cURL:

```shell
curl 'https://socialtap.dev/v1/tiktok/top_ads' \
  -H "x-api-key: $SOCIALTAP_API_KEY"
```

TypeScript SDK:

```typescript
import { SocialTap } from "socialtap";

const client = new SocialTap(); // apiKey defaults to process.env.SOCIALTAP_API_KEY

const res = await client.tiktok.topAds.list({});
console.log(res.data);
console.log(res.credits.charged, res.meta.request_id);
```

Node.js (fetch):

```javascript
const params = new URLSearchParams({
});
const res = await fetch(`https://socialtap.dev/v1/tiktok/top_ads?${params}`, {
  headers: { "x-api-key": process.env.SOCIALTAP_API_KEY ?? "" },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
const { data, page, meta } = body;
console.log(data, meta.credits_charged);
```

Python (requests):

```python
import os

import requests

res = requests.get(
    "https://socialtap.dev/v1/tiktok/top_ads",
    params={},
    headers={"x-api-key": os.environ["SOCIALTAP_API_KEY"]},
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
data, page, meta = body["data"], body["page"], body["meta"]
print(data, meta["credits_charged"])
```

Go (net/http):

```go
package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"net/url"
	"os"
)

func main() {
	q := url.Values{}
	req, err := http.NewRequest("GET", "https://socialtap.dev/v1/tiktok/top_ads?"+q.Encode(), nil)
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("x-api-key", os.Getenv("SOCIALTAP_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	var body struct {
		Data  json.RawMessage `json:"data"`
		Page  json.RawMessage `json:"page"`
		Meta  map[string]any  `json:"meta"`
		Error *struct {
			Code    string `json:"code"`
			Message string `json:"message"`
		} `json:"error"`
	}
	if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
		log.Fatal(err)
	}
	if body.Error != nil {
		log.Fatalf("%s: %s", body.Error.Code, body.Error.Message)
	}
	fmt.Println(string(body.Data), body.Meta["credits_charged"])
}
```

200 OK:

```json
{
  "data": [
    {
      "advertiser": {
        "avatar_url": null,
        "display_name": null,
        "id": null,
        "is_verified": null,
        "url": null,
        "username": null
      },
      "approximate_fields": [],
      "audience_size": null,
      "country_codes": [
        "US"
      ],
      "creatives": [
        {
          "body": null,
          "cta_text": null,
          "link_description": null,
          "link_url": null,
          "media": [
            {
              "alt_text": null,
              "duration_ms": 20781,
              "expires_at": "2026-10-25T18:00:00Z",
              "height": 720,
              "thumbnail_url": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/oUIHIbBqBgTQc9Ni3Es7fBJAe3dDvFrOsUhwGD~tplv-noop.image?dr=18692&refresh_token=64c44a34&x-expires=4070908800&x-signature=SCRUBBED&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=317596d8&idc=my&VideoID=v14033g50000davc7dvog65l…",
              "type": "video",
              "url": "https://v16m-default.tiktokcdn.com/SCRUBBED/f2a52380/video/tos/alisg/tos-alisg-ve-0051c001-sg/oQQwvwCN2QbID92BEqngivDqFDfgAB6EFIf8cY/?a=0&bti=NTU4QDM1NGA%3D&&bt=874&ft=cApXJCz7ThWHd6C8LGZmo0P&mime_type=video_mp4&rc=aDpnaDs4aWQ3NDM5N2Q6NkBpajdnM285cmdmZDMzODYzNEAuMi0tMzRhXmAxXjAzX…",
              "width": 720
            }
          ],
          "title": "Flooring Sale This Week Only!"
        }
      ],
      "first_shown_at": null,
      "id": "7691721167887056917",
      "impressions": null,
      "is_active": null,
      "is_political": null,
      "languages": [],
      "last_shown_at": null,
      "paid_by": null,
      "platform": "tiktok",
      "platform_specific": {
        "tiktok": {
          "advertiser_business_id": null,
          "advertiser_registry_location": null,
          "budget": "low",
          "category": "Interior Design & Decorating Services",
          "ctr_top_percent": 63,
          "is_removed": null,
          "like_count": 7,
          "objective": "Lead Generation",
          "rank": 1,
          "removal_country_codes": [],
          "removal_reasons": [],
          "targeting": null
        }
      },
      "publisher_platforms": [
        "tiktok"
      ],
      "reach": null,
      "spend": null,
      "type": "video",
      "unknown_fields": [
        "languages",
        "platform_specific.tiktok.removal_country_codes",
        "platform_specific.tiktok.removal_reasons"
      ],
      "url": "https://ads.tiktok.com/business/creativecenter/topads/7691721167887056917/pc/en"
    },
    {
      "advertiser": {
        "avatar_url": null,
        "display_name": null,
        "id": null,
        "is_verified": null,
        "url": null,
        "username": null
      },
      "approximate_fields": [],
      "audience_size": null,
      "country_codes": [
        "US"
      ],
      "creatives": [
        {
          "body": null,
          "cta_text": null,
          "link_description": null,
          "link_url": null,
          "media": [
            {
              "alt_text": null,
              "duration_ms": 25282,
              "expires_at": "2026-10-25T18:00:00Z",
              "height": 1280,
              "thumbnail_url": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/oUhDPioYDsJVOA9BI3aizgYdEAzkFL5bjAvAM~tplv-noop.image?dr=18692&refresh_token=c8a4f8ed&x-expires=4070908800&x-signature=SCRUBBED&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=317596d8&idc=my&VideoID=v14033g50000db1outnog65j5…",
              "type": "video",
              "url": "https://v16m-default.tiktokcdn.com/SCRUBBED/f2a52380/video/tos/alisg/tos-alisg-ve-0051c001-sg/ocgG0NLbIeoARfLAVnwAkGxeIvWbCbGhHgDhIi/?a=0&bti=NTU4QDM1NGA%3D&&bt=1088&ft=cApXJCz7ThWHd6C8LGZmo0P&mime_type=video_mp4&rc=NmY3PGlmOmk4ZjZkZzw6aEBpanc3bG05cndyZTMzODYzNEBgLjQxNDU0NTAxMF4y…",
              "width": 720
            }
          ],
          "title": "9 Home Elements That Age Your Space Instantly"
        }
      ],
      "first_shown_at": null,
      "id": "7693148617658236936",
      "impressions": null,
      "is_active": null,
      "is_political": null,
      "languages": [],
      "last_shown_at": null,
      "paid_by": null,
      "platform": "tiktok",
      "platform_specific": {
        "tiktok": {
          "advertiser_business_id": null,
          "advertiser_registry_location": null,
          "budget": "low",
          "category": "Lifestyle News",
          "ctr_top_percent": 50,
          "is_removed": null,
          "like_count": 5,
          "objective": "Traffic",
          "rank": 2,
          "removal_country_codes": [],
          "removal_reasons": [],
          "targeting": null
        }
      },
      "publisher_platforms": [
        "tiktok"
      ],
      "reach": null,
      "spend": null,
      "type": "video",
      "unknown_fields": [
        "languages",
        "platform_specific.tiktok.removal_country_codes",
        "platform_specific.tiktok.removal_reasons"
      ],
      "url": "https://ads.tiktok.com/business/creativecenter/topads/7693148617658236936/pc/en"
    },
    {
      "advertiser": {
        "avatar_url": null,
        "display_name": null,
        "id": null,
        "is_verified": null,
        "url": null,
        "username": null
      },
      "approximate_fields": [],
      "audience_size": null,
      "country_codes": [
        "US"
      ],
      "creatives": [
        {
          "body": null,
          "cta_text": null,
          "link_description": null,
          "link_url": null,
          "media": [
            {
              "alt_text": null,
              "duration_ms": 27243,
              "expires_at": "2026-10-25T18:00:00Z",
              "height": 1280,
              "thumbnail_url": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/oEqAUk2MnB3I3AFNmBtQhsfDOuDUgBftuV6DE8~tplv-noop.image?dr=18692&refresh_token=331ddbb4&x-expires=4070908800&x-signature=SCRUBBED&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=317596d8&idc=my&VideoID=v14033g50000datnapvog65j…",
              "type": "video",
              "url": "https://v16m-default.tiktokcdn.com/SCRUBBED/f2a52380/video/tos/alisg/tos-alisg-ve-0051c001-sg/o8PquQDWIBBEHK7hfDAgERAFHo6hieiTXWvNQh/?a=0&bti=NTU4QDM1NGA%3D&&bt=2105&ft=cApXJCz7ThWHd6C8LGZmo0P&mime_type=video_mp4&rc=aTlkNDY6ODkzNzlpaWVnZ0BpM3U8N205cnNxZDMzODYzNEA0NDVhYmJgNmIxXmNj…",
              "width": 720
            }
          ],
          "title": "Залишайте заявку, щоб дізнатися більше"
        }
      ],
      "first_shown_at": null,
      "id": "7690605832515158037",
      "impressions": null,
      "is_active": null,
      "is_political": null,
      "languages": [],
      "last_shown_at": null,
      "paid_by": null,
      "platform": "tiktok",
      "platform_specific": {
        "tiktok": {
          "advertiser_business_id": null,
          "advertiser_registry_location": null,
          "budget": "low",
          "category": "Home Decor",
          "ctr_top_percent": 88,
          "is_removed": null,
          "like_count": 6,
          "objective": "Lead Generation",
          "rank": 3,
          "removal_country_codes": [],
          "removal_reasons": [],
          "targeting": null
        }
      },
      "publisher_platforms": [
        "tiktok"
      ],
      "reach": null,
      "spend": null,
      "type": "video",
      "unknown_fields": [
        "languages",
        "platform_specific.tiktok.removal_country_codes",
        "platform_specific.tiktok.removal_reasons"
      ],
      "url": "https://ads.tiktok.com/business/creativecenter/topads/7690605832515158037/pc/en"
    }
  ],
  "page": {
    "has_more": false,
    "next_cursor": null,
    "next_cursor_expires_at": null,
    "end_reason": "platform_limit"
  },
  "meta": {
    "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
    "platform": "tiktok",
    "source": "api",
    "is_cached": false,
    "credits_charged": 1,
    "latency_ms": 1000,
    "fetched_at": "2026-10-25T12:00:00Z",
    "input": null,
    "credits_remaining": 9999,
    "client_request_id": null,
    "warnings": []
  }
}
```

Long arrays and strings are shortened for display; real responses are complete.

> [!NOTE]
>
> **Good to know**
>
> - Logged out, Creative Center serves only the first page of each board, so the page ends with page.end_reason platform_limit.
> - Each filter and rank_by value is its own board, so combine them to read more ads.
> - platform_specific.tiktok.ctr_top_percent is a percentile, not a rate: a smaller value means a higher click-through rate.
> - The board shows no spend, impressions or reach, so those fields are null.
> - country_codes is the board's market, and an ad can run in more markets than the one you asked for.
> - advertiser holds the brand name the board shows and no account, and advertiser.display_name is null when the board shows no brand.
> - Video links are TikTok's signed CDN links and expire at media\[\].expires_at.
> - A market Creative Center publishes no board for returns invalid_input naming the markets it does.

## Authorizations

`x-api-key`stringheaderrequired

Your API key. [Authentication](https://socialtap.dev/docs/authentication/index.md)

## Query parameters

| Name | Type | Description | Example |
| --- | --- | --- | --- |
| `country` optional | `string`<br>iso3166-1-alpha-2 | Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The market whose board to read, one of those Creative Center publishes: AR, AU, BR, CA, CO, FR, DE, ID, IT, JP, MY, MX, NL, PK, PH, RO, SA, SG, ZA, KR, ES, SE, TH, TR, AE, GB, US, VN. | `US` |
| `period` optional | `string` | The window the ranking counts over, in days back from the platform's latest update (each endpoint lists its own). Creative Center's windows: 7, 30 (default) or 180 days. Each window is its own board.<br>One of `7`, `30`, `180` | `7` |
| `rank_by` optional | `string` | How Creative Center ranks the board: for_you (its own blend, the default), or best first by impressions, likes, click-through rate (ctr), conversion rate (cvr), or the share of viewers who watched two or six seconds.<br>One of `for_you`, `impressions`, `likes`, `ctr`, `cvr`, `two_second_view_rate`, `six_second_view_rate` | `likes` |
| `industry` optional | `string` | Only ads Creative Center files under this industry (or one of its sub-industries). Omit for every industry.<br>One of `education`, `vehicle_and_transportation`, `baby_kids_and_maternity`, `beauty_and_personal_care`, `tech_and_electronics`, `travel`, `household_products`, `pets`, `home_improvement`, `apparel_and_accessories`, `news_and_entertainment`, `games`, `food_and_beverage`, `sports_and_outdoor`, `health`, `financial_services`, `appliances`, `apps`, `business_services`, `life_services`, `e_commerce_non_app` | `apps` |
| `objective` optional | `string` | Only ads whose campaign optimized for this objective. Omit for every objective.<br>One of `traffic`, `app_installs`, `conversions`, `video_views`, `reach`, `lead_generation`, `product_sales`, `app_promotion` | `conversions` |
| `ad_language` optional | `string` | Only ads in this language (zh-Hant is Traditional Chinese). Omit for every language.<br>One of `en`, `es`, `ar`, `vi`, `th`, `de`, `id`, `pt`, `fr`, `ms`, `nl`, `ja`, `it`, `ro`, `zh-Hant`, `ko` | `en` |
| `limit` optional | `integer`<br>min 1<br>max 20 | Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for. | `20` |
| `cursor` optional | `string` | page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page. | — |

Unknown parameters are rejected with a suggestion, never ignored ([Requests](https://socialtap.dev/docs/requests/index.md)). `limit` and `cursor` page through the list: see Pagination.

**Parameters every endpoint accepts**

| Name | Type | Description | Example |
| --- | --- | --- | --- |
| `max_age` optional | `integer`<br>min 0 | Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent. | — |
| `fields` optional | `string` | Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments\[\].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole. | — |

## Response

### 200

`{data, page, meta}`. `data` is an array of up to 20 [ad](https://socialtap.dev/resources/ad/index.md) objects, Creative Center's rank by rank_by, best first; `page` says how to get the next page; `meta` describes the request ([meta](https://socialtap.dev/docs/reference/index.md#meta)). Fields only TikTok Ad Library has are under `platform_specific.tiktok`.

| Field | Type | Description |
| --- | --- | --- |
| `data[].platform` | `string` | Library owner's platform ID (facebook for Meta's library, tiktok, google, linkedin). |
| `data[].id` | `string` | Library ad ID (string). |
| `data[].url` | `string` (uri) | Public library page of the ad. |
| `data[].advertiser` | `object` | The advertising page, business or account. |
| `data[].advertiser.id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `data[].advertiser.username` | `string` or `null` | Handle without the @; null when the account has none. |
| `data[].advertiser.display_name` | `string` or `null` | Display name shown on the profile. |
| `data[].advertiser.url` | `string` (uri) or `null` | Canonical profile URL. |
| `data[].advertiser.avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `data[].advertiser.is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `data[].paid_by` | `string` or `null` | Disclosed payer ("Paid for by"). |
| `data[].is_active` | `boolean` or `null` | True while the ad is running. |
| `data[].first_shown_at` | `string` (date-time) or `null` | First delivery, RFC 3339 UTC (often date-only: see approximate_fields). |
| `data[].last_shown_at` | `string` (date-time) or `null` | Last delivery, RFC 3339 UTC; null while active. |
| `data[].type` | `string` | Creative shape. New values may be added; treat unknown values as other.<br>One of `image`, `video`, `carousel`, `text`, `dynamic`, `other` |
| `data[].publisher_platforms` | `string[]` | Where it ran, lowercase IDs (facebook, instagram, messenger, audience_network, youtube, …); \[\] if not disclosed. |
| `data[].creatives` | `object[]` | The ad's creatives: one per card of a carousel and per variation of a dynamic or catalog ad, else one for the ad itself; \[\] if none are shown. |
| `data[].creatives[].title` | `string` or `null` | Headline. |
| `data[].creatives[].body` | `string` or `null` | Primary text. |
| `data[].creatives[].link_url` | `string` (uri) or `null` | Destination URL. |
| `data[].creatives[].link_description` | `string` or `null` | Link description text. |
| `data[].creatives[].cta_text` | `string` or `null` | Call-to-action label (e.g. Shop now). |
| `data[].creatives[].media` | `object[]` | Images and videos of this creative; \[\] if none. |
| `data[].creatives[].media[].type` | `string` | Kind of file. New values may be added; treat unknown values as other.<br>One of `image`, `video`, `audio`, `gif` |
| `data[].creatives[].media[].url` | `string` (uri) or `null` | Direct file URL; null when the platform withholds it, or when the link would only work from SocialTap's network or with a login. Often signed and expiring: see expires_at. |
| `data[].creatives[].media[].expires_at` | `string` (date-time) or `null` | When url stops working, RFC 3339 UTC, read from the platform's signed URL; null when unknown or when it does not expire. |
| `data[].creatives[].media[].thumbnail_url` | `string` (uri) or `null` | Poster or preview image URL. |
| `data[].creatives[].media[].width` | `integer` or `null` | Width in pixels. |
| `data[].creatives[].media[].height` | `integer` or `null` | Height in pixels. |
| `data[].creatives[].media[].duration_ms` | `integer` or `null` | Duration in milliseconds (video and audio only). |
| `data[].creatives[].media[].alt_text` | `string` or `null` | Accessibility text provided by the author or platform. |
| `data[].languages` | `string[]` | BCP-47 languages of the ad; \[\] if not disclosed. |
| `data[].country_codes` | `string[]` | ISO 3166-1 alpha-2 countries where it was shown; \[\] if not disclosed. |
| `data[].is_political` | `boolean` or `null` | Categorized as a political or social-issue ad; false when the library files it under another category, null when it shows none. |
| `data[].impressions` | `object` or `null` | Impressions or times shown range; null when not disclosed. |
| `data[].impressions.lower_bound` | `integer` | Inclusive lower bound. |
| `data[].impressions.upper_bound` | `integer` or `null` | Inclusive upper bound; null when open-ended (e.g. ">1M"). Equal to lower_bound when exact. |
| `data[].reach` | `object` or `null` | Unique users reached range; null when not disclosed. |
| `data[].reach.lower_bound` | `integer` | Inclusive lower bound. |
| `data[].reach.upper_bound` | `integer` or `null` | Inclusive upper bound; null when open-ended (e.g. ">1M"). Equal to lower_bound when exact. |
| `data[].audience_size` | `object` or `null` | Estimated target audience size range; null when not disclosed. |
| `data[].audience_size.lower_bound` | `integer` | Inclusive lower bound. |
| `data[].audience_size.upper_bound` | `integer` or `null` | Inclusive upper bound; null when open-ended (e.g. ">1M"). Equal to lower_bound when exact. |
| `data[].spend` | `object` or `null` | Spend range; null when not disclosed. |
| `data[].spend.lower_bound` | `integer` | Inclusive lower bound, in whole units of currency. |
| `data[].spend.upper_bound` | `integer` or `null` | Inclusive upper bound in whole units of currency; null when open-ended. |
| `data[].spend.currency` | `string` | ISO 4217 currency code, uppercase (USD). |
| `data[].platform_specific` | `object` | Fields only this platform has, under its ID (platform_specific.\<platform>); each null when unknown. |
| `data[].platform_specific.tiktok` | `object` or `null` | A TikTok ad's own fields. |
| `data[].platform_specific.tiktok.is_removed` | `boolean` or `null` | TikTok took the ad down (its rules or local law), in some or all regions. |
| `data[].platform_specific.tiktok.removal_reasons` | `string[]` | TikTok's reasons for the takedown; \[\] when none (in unknown_fields when not shown). |
| `data[].platform_specific.tiktok.category` | `string` or `null` | The ad's topic as TikTok files it (Apps, Food & Beverage). |
| `data[].platform_specific.tiktok.objective` | `string` or `null` | The campaign objective (Reach, Traffic). |
| `data[].platform_specific.tiktok.removal_country_codes` | `string[]` | Countries where TikTok took the ad down (ISO 3166-1 alpha-2); \[\] when it was not taken down (in unknown_fields when not shown). |
| `data[].platform_specific.tiktok.targeting` | `object` or `null` | Whom the advertiser targeted and whom the ad reached, per country; null when not shown. |
| `data[].platform_specific.tiktok.targeting.countries` | `object[]` | Per country it ran in: the ages and genders targeted and the unique users reached. |
| `data[].platform_specific.tiktok.targeting.countries[].country_code` | `string` | ISO 3166-1 alpha-2 country code. |
| `data[].platform_specific.tiktok.targeting.countries[].reach` | `object` or `null` | Unique users the ad reached there (rounded: approximate_fields); null when not shown. |
| `data[].platform_specific.tiktok.targeting.countries[].reach.lower_bound` | `integer` | Inclusive lower bound. |
| `data[].platform_specific.tiktok.targeting.countries[].reach.upper_bound` | `integer` or `null` | Inclusive upper bound; null when open-ended (e.g. ">1M"). Equal to lower_bound when exact. |
| `data[].platform_specific.tiktok.targeting.countries[].age_ranges` | `string[]` | Age ranges targeted (13-17, 18-24, 25-34, 35-44, 45-54, 55+); \[\] when not shown. |
| `data[].platform_specific.tiktok.targeting.countries[].genders` | `string[]` | Genders targeted (female, male, unknown); \[\] when not shown. |
| `data[].platform_specific.tiktok.targeting.countries[].breakdown` | `object[]` | Unique users reached there by age range and gender, the segments TikTok shows a number for; \[\] when none. |
| `data[].platform_specific.tiktok.targeting.countries[].breakdown[].age_range` | `string` | Age range (18-24, 55+). |
| `data[].platform_specific.tiktok.targeting.countries[].breakdown[].gender` | `string` | female, male or unknown. |
| `data[].platform_specific.tiktok.targeting.countries[].breakdown[].reach` | `object` | Unique users reached (rounded: approximate_fields). |
| `data[].platform_specific.tiktok.targeting.countries[].breakdown[].reach.lower_bound` | `integer` | Inclusive lower bound. |
| `data[].platform_specific.tiktok.targeting.countries[].breakdown[].reach.upper_bound` | `integer` or `null` | Inclusive upper bound; null when open-ended (e.g. ">1M"). Equal to lower_bound when exact. |
| `data[].platform_specific.tiktok.targeting.interests` | `string[]` | Interest categories targeted; \[\] when none. |
| `data[].platform_specific.tiktok.targeting.video_interactions` | `string[]` | Video interaction categories targeted; \[\] when none. |
| `data[].platform_specific.tiktok.targeting.creator_interactions` | `string[]` | Creator interaction categories targeted; \[\] when none. |
| `data[].platform_specific.tiktok.targeting.provinces` | `string[]` | Provinces or states targeted within the countries; \[\] when none. |
| `data[].platform_specific.tiktok.targeting.cities` | `string[]` | Cities targeted; \[\] when none. |
| `data[].platform_specific.tiktok.targeting.device_models` | `string[]` | Device models targeted; \[\] when any. |
| `data[].platform_specific.tiktok.targeting.operating_systems` | `string[]` | Operating systems targeted; \[\] when any. |
| `data[].platform_specific.tiktok.targeting.is_custom_audience` | `boolean` or `null` | The advertiser targeted a custom audience (its own customer list or a lookalike). |
| `data[].platform_specific.tiktok.targeting.is_audience_excluded` | `boolean` or `null` | The advertiser excluded a custom audience. |
| `data[].platform_specific.tiktok.targeting.is_high_spending_power` | `boolean` or `null` | Targeted at users TikTok rates as high spenders. |
| `data[].platform_specific.tiktok.advertiser_business_id` | `string` or `null` | The advertiser's TikTok business ID (search_ads advertiser_id). |
| `data[].platform_specific.tiktok.advertiser_registry_location` | `string` or `null` | Where the advertiser is registered (Italy). |
| `data[].platform_specific.tiktok.rank` | `integer` or `null` | Place on Creative Center's Top Ads board, 1 first; null off the board. |
| `data[].platform_specific.tiktok.like_count` | `integer` or `null` | Likes the ad drew, as Creative Center counts them; null off the board. |
| `data[].platform_specific.tiktok.ctr_top_percent` | `number` or `null` | Click-through rate rank: the ad is in the top this many percent of ads (4 = top 4%); null off the board. |
| `data[].platform_specific.tiktok.budget` | `string` or `null` | Creative Center's budget level; null off the board. New values may be added; treat unknown values as other.<br>One of `low`, `medium`, `high` |
| `data[].approximate_fields` | `string[]` | JSON paths of values that are rounded, date-only or parsed from display text. A list path (external_links) means the list may be incomplete. \[\] when all exact. |
| `data[].unknown_fields` | `string[]` | JSON paths of lists whose \[\] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. \[\] when every list is known. |

not_found is item-level: the request was fine, the item can't be returned.

### 400

400 Bad Request: 2 error codes. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `invalid_input` | 400 | No | A parameter is missing or malformed, or the link is not one this endpoint takes. | Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one. |
| `invalid_cursor` | 400 | No | The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. | Repeat the original request without cursor to start the list again. |

### 401

401 Unauthorized: 1 error code. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `unauthorized` | 401 | No | The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. | Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url. |

### 402

402 Payment Required: 2 error codes. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `insufficient_credits` | 402 | No | The account does not have enough credits for this request. | Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically. |
| `spend_limit_reached` | 402 | No | The API key reached its spend limit for this period. The account may still have credits. | Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically. |

### 403

403 Forbidden: 1 error code. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `forbidden` | 403 | No | The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. | Act on details.reason. suspended: contact [support](mailto:support@socialtap.dev). scope: use a key with details.required_scope. previous_secret: use the new secret. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP. |

### 404

404 Not Found: 1 error code. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `not_found` | 404 | No | The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). | Check the link or ID. Do not retry. |

### 429

429 Too Many Requests: 1 error code. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `rate_limited` | 429 | Yes, later | The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. | Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask [support](mailto:support@socialtap.dev) to raise the ceiling; without an API key, send one. |

### 451

451: 1 error code. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `unavailable_for_legal_reasons` | 451 | No | We removed this item after a copyright notice or another legal request, so we don't return it. The request was free. A list leaves such items out instead, with an items_omitted warning. | Do not retry. The item stays unavailable unless the notice is withdrawn. |

### 500

500 Internal Error: 1 error code. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `internal` | 500 | Yes, later | An unexpected error on SocialTap's side. | Retry with backoff. If it keeps happening, contact [support](mailto:support@socialtap.dev) with the request_id. |

### 502

502 Bad Gateway: 1 error code. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `upstream_error` | 502 | Yes, later | The platform failed, or answered with something we could not read. | Retry with backoff. Failed requests are free. |

### 503

503 Unavailable: 2 error codes. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `upstream_blocked` | 503 | Yes, later | The platform refused every attempt, our own retries included. | Retry later with backoff. Failed requests are free. |
| `overloaded` | 503 | Yes, later | SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. | Retry after the seconds in the retry-after header. Failed requests are free. |

## Pagination

Items come in pages, **Creative Center's rank by rank_by, best first**. To get the next page, send **the same request plus `cursor`** set to `page.next_cursor` from the previous response. Keep every other parameter the same (limit, max_age and fields may change); anything else that differs is rejected. When `page.has_more` is `false` the walk is over, and `page.end_reason` says why: only `end` means you have every item (the others say the platform or a page cap stopped the walk early).

- **Order**: Creative Center's rank by rank_by, best first
- **Page size**: Up to 20 best-performing ads (the default; `limit` lowers it)
- **Cursor lifetime**: 24 hours; don't store cursors
- **Price**: Per page, 1 credit

### The `page` object

| Field | Type | Description |
| --- | --- | --- |
| `page.has_more` | `boolean` | True when another page exists; then next_cursor is set. An empty page with has_more true is not the end. |
| `page.next_cursor` | `string` or `null` | Pass as cursor, with the same other parameters, to get the next page; null at the end. |
| `page.next_cursor_expires_at` | `string` (date-time) or `null` | When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors. |
| `page.end_reason` | `string` or `null` | Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.<br>One of `end`, `platform_limit`, `max_pages` |

### Next page

cURL: next page:

```shell
curl 'https://socialtap.dev/v1/tiktok/top_ads?cursor=NEXT_CURSOR' \
  -H "x-api-key: $SOCIALTAP_API_KEY"
```

- The price is per page: each successful page costs the same, whatever `limit` is and however many items it has. Empty pages are charged too (an empty page with `has_more: true` is not the end).
- A `limit` below 20 doesn't save credits: the next request serves the rest of the same platform page, which is fetched again and charged as a page each time, and items can shift between those requests if the platform changes the list. Omitting `limit` is the cheapest way to walk the list.
- Errors are free, including a rejected cursor.
- Pages served from the cache are free.
- An expired or altered cursor, or one sent with different parameters, fails with [`invalid_cursor`](https://socialtap.dev/docs/errors/index.md#invalid_cursor) (HTTP 400): Repeat the original request without cursor to start the list again.

[Pagination guide](https://socialtap.dev/docs/pagination/index.md)

## Pricing

From **1 credit** per page. Charged per successful page, whatever its number of items. Errors are free. The price depends on the source that produced the result, reported as `meta.source`.

| Source | Price per successful page | Per 1,000 pages |
| --- | --- | --- |
| Platform API `api` | 1 credit | $0.75–$1.97 |

**Balance, sources and what you were charged**

Your balance must be at least **1 credit** to start a request; with less, it is refused with [`insufficient_credits`](https://socialtap.dev/docs/errors/index.md#insufficient_credits) (HTTP 402) and costs nothing. Only that minimum is set aside when the request starts.

| meta.source | Source | What it means |
| --- | --- | --- |
| `api` | Platform API | The platform's public, logged-out API. |

`meta.credits_charged` and the `x-credits-charged` header show what you paid. [How credits work](https://socialtap.dev/docs/credits/index.md) · [Packs](https://socialtap.dev/pricing/index.md)

Endpoint ID `tiktok.top_ads` · operationId `tiktok.top_ads.list` · [Product overview](https://socialtap.dev/apis/tiktok/top-ads/index.md)

---

[HTML version](https://socialtap.dev/docs/reference/tiktok/top-ads/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)
