# TikTok Top Ads Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/tiktoktopads/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 1 credit per call |
| **Documentation** | https://www.piloterr.com/library/tiktoktopads-search |

## Description

Search TikTok Creative Center Top Ads by region, objective, period, and keyword. Returns ad cards and pagination (1 credit).

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/tiktoktopads/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Argentina last 30 days

```json
{
  "results": [
    {
      "ctr": 0.97,
      "url": "https://ads.tiktok.com/business/creativecenter/topads/7683821191329005569/pc/en?period=30",
      "cost": 0,
      "ad_id": "7683821191329005569",
      "format": "video",
      "headline": "DESCUBRE",
      "image_url": "https://p16.tiktokcdn.com/cover.jpg",
      "objective": "campaign_objective_lead_generation",
      "video_url": "https://v16.tiktokcdn.com/video.mp4",
      "like_count": 4120,
      "industry_key": "label_10104000000",
      "advertiser_name": "Example Brand"
    }
  ],
  "pagination": {
    "next": "https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en?period=30&region=AR&page=2",
    "page": 1,
    "cursor": "2",
    "per_page": 20,
    "total_pages": 3,
    "total_results": 47
  }
}
```

## Documentation

## Overview
Search **TikTok Top Ads** (Creative Center). Pass a **region** (`AR`), **objective** id, **period** (`7` / `30` / `180`), a **keyword**, or a **full Top Ads URL**. **1 credit** per call.

Each card includes the ad id, advertiser, headline, CTR, likes, and video preview. Pagination is `{ results, pagination }`. Open `results[].url` with the ad endpoint for the full creative.

## Quickstart
```
GET https://api.piloterr.com/v2/tiktoktopads/search?period=30
GET https://api.piloterr.com/v2/tiktoktopads/search?period=30&region=AR
GET https://api.piloterr.com/v2/tiktoktopads/search?period=30&region=AR&objective=4
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | no | Full Top Ads search URL, or a keyword |
| `keyword` | string | no | Brand / product keyword |
| `region` | string | no | ISO country code |
| `objective` | string | no | Campaign objective id (URL `object`) |
| `period` | string | no | `7`, `30` (default), or `180` |
| `order_by` | string | no | `for_you`, `reach` / `impression`, `ctr` / `like` |
| `page` / `per_page` | integer | no | Pagination |

## Related endpoints
- [TikTok Top Ads Ad](https://www.piloterr.com/library/tiktoktopads-ad)