TikTok Ads Search

Use the bundled script to search public TikTok advertisements or retrieve specific ad details. It calls only the three Frevana /apify/tiktok-ads/tasks create, status, and result APIs. Requires Bash and Python 3.9+ with the standard library; no TikTok access token or SDK is needed.

Workflow

1. Require a keyword (--query), advertiser (--advertiser-name), specific supported country, or one to one hundred unique --ad-id values. Do not combine ad IDs with any search filter. For account/campaign management, use tiktok-ads; for ordinary public posts, use a TikTok public-data skill.
2. Prefer run to create, wait, and retrieve results. Use create, status, wait, and result for separate phases. Read references/api.md for filters, defaults, supported countries, and task states.
3. Treat creation as billable: the server checks estimated credits and settles actual usage asynchronously. Record the printed client_task_id and returned task_id. After an uncertain create response, retry only with identical options and the same client ID; never automatically create a replacement task. Different parameters with the same ID return HTTP 409.
4. Wait for status=READY and result_available=true. Follow next_poll_after_ms; zero stops automatic polling. Stop on FAILED, REVIEW_REQUIRED, or RESULT_EXPIRED. A wait timeout can be resumed with the same task_id.
5. Preserve raw JSON in saved files. Summarize relevant ads for the user unless they request raw JSON. Do not imply a pending or settling task has completed. quick_search=true and unavailable ads may omit detail fields; never invent missing details.

Commands

Resolve {baseDir} to the directory containing this file.