tiktok-ad-research

TikTok ad research

Build a sourced comparison of TikTok Top Ads and explain which creative ideas are supported by observed content and public performance signals. Top Ads is a selected collection of high-performing auction ads, not every advertiser's campaigns.

Setup and requests

Set CRAWLORA_API_KEY to your key from crawlora.net. Run the bundled scripts/crawlora.sh from this skill directory or by absolute path. It sends x-api-key to https://api.crawlora.net/api/v1 and prints JSON. Keep the key in the environment. Read reference/endpoints.md for the ten Top Ads endpoints and their exact parameters.

Workflow

1. Determine the brands/product keywords, market, objective, lookback period, and requested sample size from the brief. Discover current industry, objective, language, and country IDs through /tiktok/top-ads/filters; use /locations and /location-info when the geography needs clarification.
2. Search /tiktok/top-ads/list, keeping market, period, and objective consistent across competitors. period is 7, 30, or 180; limit is at most 100. order_by accepts for_you, impression, ctr, play_2s_rate, play_6s_rate, cvr, or like. State the sort because it changes the sample.
3. Deduplicate by Top Ads material ID and fetch /tiktok/top-ads/detail for a bounded shortlist. Use the returned material ID, not a TikTok video ID. Recommendations and spotlight ads can widen discovery, but mark them as supplemental rather than silently mixing them into a matched comparison.
4. Use /tiktok/top-ads/analysis when performance over the ad's duration matters. Metrics are retain_ctr, retain_cvr, click_cnt, convert_cnt, and play_retain_cnt; period_type is 7, 30, or 180. Match metric and period across ads before comparing charts or percentiles.
5. Inspect the actual creative when the environment supports video/image viewing. If only metadata is accessible, limit conclusions to title/copy and returned fields. Do not claim to have watched a hook or heard audio from metadata alone.
6. Summarize recurring messaging, format, offer, and call-to-action patterns with linked examples. Present proposed creative tests as hypotheses; public charts do not establish what caused conversion performance.

scripts/crawlora.sh /tiktok/top-ads/filters
scripts/crawlora.sh /tiktok/top-ads/list \
  keyword=skincare country_code=US period=30 limit=10 order_by=ctr

Output and interpretation

Return a comparison with material_id, available advertiser/title, source link, country, objective, lookback, duration, observed messaging/format, returned performance fields, and retrieval time. Preserve metric labels and units as reported; a percentile is not a raw CTR, spend estimate, or ROI.

• Keyword results may mention a brand without belonging to it. Verify advertiser identity where available and mark uncertain matches.
• No matches means none in the queried Top Ads sample, not that the competitor is inactive. Describe the filters and coverage rather than claiming all ads.
• Keep signed media URLs as returned; they may expire. Retain material IDs and source-page links when available so the research can be repeated.
• The response can contain nested upstream code/msg/data. Check both the Crawlora envelope and any upstream code before treating materials as results. Stop at pagination.has_more=false or the agreed sample bound.
• On 429, back off; retry a transient 5xx once. Stop on 401/403 and report the source limitation. Preserve a partial comparison if only some details/charts load, clearly marking missing observations.