Publicités TikTok

Search TikTok ads with the same filters as the in-app TikTok Ads dashboard, or retrieve individual ad details by ID. Use GET /api/v1/tiktok-ads et GET /api/v1/tiktok-ads/{id} with your API key (dashboard /api/tt-ads is session-oriented).

OBTENIR/api/v1/tiktok-ads

Search TikTok ads. Supports keyword, niche, country, engagement (likes, comments, shares), scaling, traffic, days running, and date filters with scroll pagination.

Send Clé X-API on every request.

Query parameters

mot-cléstring
Free-text or comma-separated search terms. Aliases: q, search.
searchkeywordstring
Default: TousValues: Tous landingurl pagename adtext productname
countriesstring
Comma-separated country codes or All.
sortingstring
Default: likesValues: likes shares comments datefound lastseen adspend adsetamount consistency daysrunning
sortdirectionstring
Default: descValues: desc asc
nichesstring
Comma-separated categories (beauty, bags, car, romanticgifts, clothing, watches, jewelry, womenclothing, menclothing, toys, child, home, pet, gadgets, outdoor) or direct label_* IDs.
mininteger
Minimum likes count. Aliases: minlikes, min_likes.
Default: 1
maxinteger
Maximum likes count. Aliases: maxlikes, max_likes.
Default: 99999999
mincommentsinteger
Minimum comment count. Aliases: min_comments.
Default: 1
maxcommentsinteger
Maximum comment count. Aliases: max_comments.
Default: 9999999
minsharesinteger
Minimum share count. Aliases: min_shares.
Default: 1
maxsharesinteger
Maximum share count. Aliases: max_shares.
Default: 9999999
scalingstring
Default: TousValues: Tous upscaling nodownscaling downscaling
languagesstring
Comma-separated language codes or All. Alias: language.
websitesstring
Comma-separated platform technologies (e.g. SH, WOO, MAG, BIG) or All. Aliases: website, technologies.
fromstring
Ad start date from (Y-m-d). Alias: date_from.
tostring
Ad start date to (Y-m-d). Alias: date_to.
fromlastseenstring
Ad last seen date from (Y-m-d). Alias: last_seen_from.
tolastseenstring
Ad last seen date to (Y-m-d). Alias: last_seen_to.
product_fromstring
Product creation date from (Y-m-d). Alias: product_created_from.
product_tostring
Product creation date to (Y-m-d). Alias: product_created_to.
pagetypestring
Default: TousValues: Tous collections
mintrafficinteger
Minimum monthly store visits. Alias: traffic_min.
maxtrafficinteger
Maximum monthly store visits. Alias: traffic_max.
mindaysinteger
Minimum days running. Alias: days_min.
maxdaysinteger
Maximum days running. Alias: days_max.
scrollstring
Opaque cursor; empty on first request.
limiteinteger
Page size (max 50 on first request; stored in scroll token).
Default: 20

Demande

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-ads?keyword=skincare&searchkeyword=All&countries=US%2CCA%2CGB&sorting=likes&sortdirection=desc&niches=beauty%2Cskincare&min=1&max=99999999&mincomments=1&maxcomments=9999999&minshares=1&maxshares=9999999&scaling=All&languages=en&websites=string&from=string&to=string&fromlastseen=string&tolastseen=string&product_from=string&product_to=string&pagetype=All&mintraffic=0&maxtraffic=0&mindays=0&maxdays=0&scroll=string&limit=20"

const res = await fetch(`${ORIGIN}/api/v1/tiktok-ads?keyword=skincare&searchkeyword=All&countries=US%2CCA%2CGB&sorting=likes&sortdirection=desc&niches=beauty%2Cskincare&min=1&max=99999999&mincomments=1&maxcomments=9999999&minshares=1&maxshares=9999999&scaling=All&languages=en&websites=string&from=string&to=string&fromlastseen=string&tolastseen=string&product_from=string&product_to=string&pagetype=All&mintraffic=0&maxtraffic=0&mindays=0&maxdays=0&scroll=string&limit=20`, {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    f"{ORIGIN}/api/v1/tiktok-ads?keyword=skincare&searchkeyword=All&countries=US%2CCA%2CGB&sorting=likes&sortdirection=desc&niches=beauty%2Cskincare&min=1&max=99999999&mincomments=1&maxcomments=9999999&minshares=1&maxshares=9999999&scaling=All&languages=en&websites=string&from=string&to=string&fromlastseen=string&tolastseen=string&product_from=string&product_to=string&pagetype=All&mintraffic=0&maxtraffic=0&mindays=0&maxdays=0&scroll=string&limit=20",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
)
data = res.json()

Response

{
    "success": true,
    "data": [
        {
            "active": 1,
            "collationID": "7518543522271641616",
            "postId": "7518543522271641616",
            "productid": "7518543522271641616",
            "vidid": "v09025g40000d1aa5e7og65i01bfeclg",
            "adFormat": "video",
            "urlStore": "https://wailana.com/namaste/?utm_source=tiktok&utm_medium=paid",
            "video": "https://media.winninghunter.com/tiktok/video/bed987330602cbdf2fee9dd7037538bc868b2d1c431c00feeec52677538585e1.mp4",
            "image": "https://media.winninghunter.com/tiktok/image/fd47244b4c1fb9ac67af55abef6e0835ae7191e576aedf427a83fcfe83fec61e.jpg",
            "poster": "https://media.winninghunter.com/tiktok/image/fd47244b4c1fb9ac67af55abef6e0835ae7191e576aedf427a83fcfe83fec61e.jpg",
            "updated_at": "2026-01-28T01:31:54+00:00",
            "likeCount": 7795549,
            "commentCount": 26760,
            "shareCount": 16049,
            "pageName": "Wai Lana Yoga",
            "description": "\"Namaste\" Music Video by Wai Lana | Respect, Peace & Unity",
            "copy": "\"Namaste\" Music Video by Wai Lana | Respect, Peace & Unity",
            "caption": "\"Namaste\" Music Video by Wai Lana | Respect, Peace & Unity",
            "niche": [
                "label_23116000000"
            ],
            "platform": "tiktok",
            "cost": 2,
            "ctr": 0.09,
            "industry_key": "label_23116000000",
            "objective_key": "campaign_objective_video_view",
            "objectives": [
                "campaign_objective_video_view"
            ],
            "technologies": [
                "WP",
                "GM"
            ],
            "countries": [
                "US",
                "CA",
                "GB",
                "AU",
                "DE"
            ],
            "pagecountries": [
                "US",
                "CA",
                "GB",
                "AU",
                "DE"
            ],
            "pagecountrycount": 34,
            "adscount": 1,
            "lastSeen": "2026-01-28",
            "created_at": "2026-01-28T01:31:54+00:00",
            "found_at": "2026-01-28T01:31:54+00:00",
            "scaling": 0,
            "daysrunning": 30,
            "total_ads": 1,
            "adscore": "Winning",
            "adscore_reasons": [
                "Estimated spend is high for this creative ($100+)"
            ],
            "revenue": "10444424.18",
            "total_adspend": 3181255.55,
            "store_traffic": {
                "domain": "wailana.com",
                "monthly_visits": 4741,
                "source": "similarweb",
                "canonical_domain": "wailana.com",
                "monthly_visits_updated_at": "2026-01-28T01:32:46.878Z"
            }
        }
    ],
    "scroll": "6c12e8bfb66aa6047ea523a00d8ca298",
    "limit": 20,
    "total": 10000,
    "nextscrapetime": 1787888558
}

OBTENIR/api/v1/tiktok-ads/{id}

Retrieve full details and metadata for a single TikTok ad creative by its ID, collation ID, or post ID.

Send Clé X-API on every request.

Path parameters

idstringrequired
TikTok document ID, collation ID, product ID, or post ID.

Demande

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-ads/7518543522271641616"

const res = await fetch(`${ORIGIN}/api/v1/tiktok-ads/7518543522271641616`, {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    f"{ORIGIN}/api/v1/tiktok-ads/7518543522271641616",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
)
data = res.json()

Response

{
    "success": true,
    "data": {
        "active": 1,
        "collationID": "7518543522271641616",
        "postId": "7518543522271641616",
        "productid": "7518543522271641616",
        "vidid": "v09025g40000d1aa5e7og65i01bfeclg",
        "adFormat": "video",
        "urlStore": "https://wailana.com/namaste/?utm_source=tiktok&utm_medium=paid",
        "video": "https://media.winninghunter.com/tiktok/video/bed987330602cbdf2fee9dd7037538bc868b2d1c431c00feeec52677538585e1.mp4",
        "image": "https://media.winninghunter.com/tiktok/image/fd47244b4c1fb9ac67af55abef6e0835ae7191e576aedf427a83fcfe83fec61e.jpg",
        "poster": "https://media.winninghunter.com/tiktok/image/fd47244b4c1fb9ac67af55abef6e0835ae7191e576aedf427a83fcfe83fec61e.jpg",
        "updated_at": "2026-01-28T01:31:54+00:00",
        "likeCount": 7795549,
        "commentCount": 26760,
        "shareCount": 16049,
        "pageName": "Wai Lana Yoga",
        "description": "\"Namaste\" Music Video by Wai Lana | Respect, Peace & Unity",
        "copy": "\"Namaste\" Music Video by Wai Lana | Respect, Peace & Unity",
        "caption": "\"Namaste\" Music Video by Wai Lana | Respect, Peace & Unity",
        "niche": [
            "label_23116000000"
        ],
        "platform": "tiktok",
        "cost": 2,
        "ctr": 0.09,
        "industry_key": "label_23116000000",
        "objective_key": "campaign_objective_video_view",
        "objectives": [
            "campaign_objective_video_view"
        ],
        "technologies": [
            "WP",
            "GM"
        ],
        "countries": [
            "US",
            "CA",
            "GB",
            "AU",
            "DE"
        ],
        "created_at": "2026-01-28T01:31:54+00:00",
        "lastSeen": "2026-01-28",
        "store_traffic": {
            "domain": "wailana.com",
            "monthly_visits": 4741,
            "source": "similarweb",
            "canonical_domain": "wailana.com"
        }
    }
}

{
    "success": false,
    "error": "not_found",
    "message": "TikTok ad not found"
}

Pagination

TikTok Ads search uses opaque scroll cursor pagination (matching Meta Ad Library and Pinterest Ads):

Initial request: Make a request without a scroll parameter. Specify optional limite (default 20, max 50).
Next page: Pass the returned scroll token in the subsequent request along with the exact same query filters.
End of results: When scroll retours null or fewer rows than limite are returned, all matching ads have been fetched.

Quick examples

Search by keyword with engagement filters

curl -sS -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-ads?keyword=skincare&min=1000&countries=US&sorting=likes&limit=20"

Next page with scroll token

curl -sS -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-ads?keyword=skincare&min=1000&countries=US&sorting=likes&scroll=PASTE_SCROLL_TOKEN_HERE"

Single ad detail lookup

curl -sS -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-ads/7489218491028374"

Publicités TikTok

Query parameters

Path parameters

Pagination#

Quick examples#

Search by keyword with engagement filters#

Next page with scroll token#

Single ad detail lookup#

Pagination

Quick examples

Search by keyword with engagement filters

Next page with scroll token

Single ad detail lookup