Piloterr

TikTok Top Ads Ad

GET
/v2/tiktoktopads/ad

Get one TikTok Creative Center Top Ad by URL or id: creative, landing page, CTR, and engagement (1 credit).

Credit cost: 1 credit per call

Authentification

ApiKeyAuth
headerx-api-key<token>

Your API key. Include it in the x-api-key header for every request.

Paramètres de requête

query*string

Ad id or detail URL from search.

Example:

https://ads.tiktok.com/business/creativecenter/topads/7686267188656750612/pc/en?period=30
fields?string

Comma-separated list of response fields to return, with dot notation for nested fields (e.g. name,location.city).

is_async?boolean

Run the request as a background job: the API answers 202 with a job_id to poll on GET /v1/jobs/{id}.

Defaultfalse
soft_fail?boolean

Return HTTP 200 even when the request fails; the error is in the error field of the body.

Defaultfalse

Corps de la réponse

Successful response

application/json
  1. response
ctr?number
url?string
cost?integer
ad_id?string
format?string
source?string
duration?number
headline?string
countries?array<string>
image_url?string
objective?string
video_url?string
like_count?integer
objectives?array<>
voice_over?unknown
share_count?integer
industry_key?string
keyword_list?unknown
landing_page?string
comment_count?integer
advertiser_name?string
Example Request
curl -X GET 'https://api.piloterr.com/v2/tiktoktopads/ad?query=string'
Example Response
{  "ctr": 0.22,  "url": "https://ads.tiktok.com/business/creativecenter/topads/7686267188656750612/pc/en?period=30",  "cost": 1,  "ad_id": "7686267188656750612",  "format": "video",  "source": "TikTok Ads Manager",  "duration": 32.9,  "headline": "25% Off Our Popular Juice Groove Router Jig. Limited Time Sale!",  "countries": [    "US"  ],  "image_url": "https://p16.tiktokcdn.com/detail-cover.jpg",  "objective": "campaign_objective_conversion",  "video_url": "https://v16.tiktokcdn.com/detail.mp4",  "like_count": 39,  "objectives": [    {      "label": "campaign_objective_conversion",      "value": 3    }  ],  "voice_over": null,  "share_count": 1,  "industry_key": "label_21103000000",  "keyword_list": null,  "landing_page": "https://craftedelements.com/products/juice-groove-router-jig",  "comment_count": 0,  "advertiser_name": "crafted elements"}