TikTok Top Ads Search

Use the bundled Bash/Python helper for Creative Center Top Ads research. Requires Bash and Python 3.9+ with the standard library. No TikTok Business token or SDK is needed.

Workflow

1. Require --keyword, one to five --start-url values, or both. Country or other filters alone are insufficient. URLs must be HTTPS on ads.tiktok.com under /business/creativecenter/topads/ or /business/creativecenter/inspiration/topads/. For Ads Library research use tiktok-ads-search; for account/campaign management use tiktok-ads.
2. Prefer run to create, wait, and fetch the complete JSON array. Use create, status, wait, and result for separate phases. Read references/api.md for all parameter allowlists, defaults, and task states.
3. Creation is billable: the server checks estimated credits and settles actual usage asynchronously. Record the printed client_task_id and returned task_id. If creation has an uncertain outcome, retry only with identical options and the same client ID; never automatically create a replacement. Changed parameters with the same ID return HTTP 409.
4. Wait for READY with result_available=true. Follow next_poll_after_ms; zero stops automatic polling. Stop on FAILED, REVIEW_REQUIRED, or RESULT_EXPIRED. Resume a timeout with wait --task-id using the existing ID.
5. Preserve saved JSON bytes and summarize relevant ads unless raw JSON is requested. Keep id as a string. Metrics and media are optional; do not infer missing values or treat media URLs as permanent archived assets.

Commands

Resolve {baseDir} to the directory containing this file.