# Monitor a competitor's new TikTok ads weekly

**Use case:** 

Only TikTok ads you have not seen before: ads an earlier run delivered are skipped and not charged, and a run that finds nothing new costs nothing. Each run reads the advertiser's ads shown in the last 7 days and returns those not delivered before, newest first, up to maxAds; an ad whose last shown day, reach band or status moved comes back marked changed. Save, Schedule it, add Slack or Gmail.

## Input

```json
{
  "advertisers": [
    "LIDL GREAT BRITAIN LIMITED"
  ],
  "keywords": [],
  "creators": [],
  "startUrls": [],
  "adIds": [],
  "searches": [],
  "resultType": "ads",
  "countries": [],
  "dateRange": "last-7-days",
  "timezone": "UTC",
  "adStatus": "all",
  "mediaType": "all",
  "ages": [],
  "gender": "all",
  "reach": [],
  "sortBy": "newest",
  "includeRemovedAds": true,
  "minDaysRunning": 0,
  "onlyActive": false,
  "topAdsCountries": [],
  "topAdsPeriod": "30",
  "topAdsSortBy": "ctr",
  "topAdsIndustries": [],
  "topAdsObjectives": [],
  "topAdsLanguages": [],
  "topAdsFormat": "all",
  "topAdsLikes": "all",
  "topAdsSweep": false,
  "topAdsSpotlight": false,
  "topAdsDetails": true,
  "topAdsMetrics": false,
  "includeDetails": true,
  "includeAdvertiserReport": false,
  "downloadMedia": "none",
  "tagAds": false,
  "analyzeAds": false,
  "ocrImageAds": false,
  "transcribeVideos": false,
  "summaryRows": false,
  "outputFormat": "full",
  "maxAds": 300,
  "maxAdsPerSearch": 0,
  "onlyNewAds": true,
  "includeEndedAds": false
}
```

## Output

```json
{
  "row_type": {
    "label": "Row type",
    "format": "string"
  },
  "surface": {
    "label": "Surface",
    "format": "string"
  },
  "creative_id": {
    "label": "Ad id",
    "format": "string"
  },
  "ad_url": {
    "label": "Ad URL",
    "format": "string"
  },
  "ad_format": {
    "label": "Ad format",
    "format": "string"
  },
  "creative_available": {
    "label": "Creative available",
    "format": "boolean"
  },
  "advertiser_name": {
    "label": "Advertiser name",
    "format": "string"
  },
  "advertiser_id": {
    "label": "Advertiser id",
    "format": "string"
  },
  "advertiser_location": {
    "label": "Advertiser location",
    "format": "string"
  },
  "payer": {
    "label": "Payer",
    "format": "string"
  },
  "advertiser_tiktok_username": {
    "label": "TikTok username",
    "format": "string"
  },
  "advertiser_tiktok_name": {
    "label": "TikTok display name",
    "format": "string"
  },
  "advertiser_tiktok_url": {
    "label": "TikTok profile",
    "format": "string"
  },
  "advertiser_tiktok_followers": {
    "label": "TikTok followers",
    "format": "integer"
  },
  "advertiser_tiktok_avatar_url": {
    "label": "TikTok avatar",
    "format": "string"
  },
  "advertiser_tiktok_account_type": {
    "label": "TikTok account type",
    "format": "string"
  },
  "creator_username": {
    "label": "Creator username",
    "format": "string"
  },
  "creator_url": {
    "label": "Creator URL",
    "format": "string"
  },
  "content_label": {
    "label": "Content label",
    "format": "string"
  },
  "body_text": {
    "label": "Body text",
    "format": "string"
  },
  "hook_text": {
    "label": "Hook text",
    "format": "string"
  },
  "hashtags": {
    "label": "Hashtags",
    "format": "array"
  },
  "mentions": {
    "label": "Mentions",
    "format": "array"
  },
  "cta": {
    "label": "CTA",
    "format": "string"
  },
  "cta_type": {
    "label": "CTA type",
    "format": "string"
  },
  "objective": {
    "label": "Objective",
    "format": "string"
  },
  "objectives": {
    "label": "Objectives",
    "format": "array"
  },
  "category": {
    "label": "Category",
    "format": "string"
  },
  "industry": {
    "label": "Industry",
    "format": "string"
  },
  "industry_id": {
    "label": "Industry id",
    "format": "string"
  },
  "destination_url": {
    "label": "Destination URL",
    "format": "string"
  },
  "landing_domain": {
    "label": "Landing domain",
    "format": "string"
  },
  "image_url": {
    "label": "Image",
    "format": "string"
  },
  "image_urls": {
    "label": "Image urls",
    "format": "array"
  },
  "cover_url": {
    "label": "Cover",
    "format": "string"
  },
  "video_url": {
    "label": "Video URL",
    "format": "string"
  },
  "video_urls": {
    "label": "Video urls",
    "format": "array"
  },
  "video_id": {
    "label": "Video id",
    "format": "string"
  },
  "video_duration_s": {
    "label": "Video seconds",
    "format": "number"
  },
  "video_width": {
    "label": "Video width",
    "format": "integer"
  },
  "video_height": {
    "label": "Video height",
    "format": "integer"
  },
  "media_expires_at": {
    "label": "Media links expire",
    "format": "string"
  },
  "first_shown": {
    "label": "First shown",
    "format": "string"
  },
  "last_shown": {
    "label": "Last shown",
    "format": "string"
  },
  "days_shown": {
    "label": "Days shown",
    "format": "integer"
  },
  "is_active": {
    "label": "Is active",
    "format": "boolean"
  },
  "tiktok_status": {
    "label": "Tiktok status",
    "format": "string"
  },
  "launched_last_7_days": {
    "label": "Launched last 7 days",
    "format": "boolean"
  },
  "launched_last_30_days": {
    "label": "Launched last 30 days",
    "format": "boolean"
  },
  "long_running": {
    "label": "Long running",
    "format": "boolean"
  },
  "posted_at": {
    "label": "Posted",
    "format": "string"
  },
  "audit_status": {
    "label": "Audit status",
    "format": "string"
  },
  "is_removed": {
    "label": "Is removed",
    "format": "boolean"
  },
  "removal_reasons": {
    "label": "Removal reasons",
    "format": "array"
  },
  "display_mode": {
    "label": "Display mode",
    "format": "string"
  },
  "reach_bucket": {
    "label": "Reach bucket",
    "format": "string"
  },
  "reach_min": {
    "label": "Reach min",
    "format": "integer"
  },
  "reach_max": {
    "label": "Reach max",
    "format": "integer"
  },
  "impressions_by_country": {
    "label": "Impressions by country",
    "format": "array"
  },
  "top_country": {
    "label": "Top country",
    "format": "string"
  },
  "countries_count": {
    "label": "Countries count",
    "format": "integer"
  },
  "regions": {
    "label": "Regions",
    "format": "array"
  },
  "audience_breakdown": {
    "label": "Audience breakdown",
    "format": "array"
  },
  "target_audience_size": {
    "label": "Target audience size",
    "format": "string"
  },
  "audience_size_min": {
    "label": "Audience size min",
    "format": "integer"
  },
  "audience_size_max": {
    "label": "Audience size max",
    "format": "integer"
  },
  "targeting_ages": {
    "label": "Targeting ages",
    "format": "array"
  },
  "targeting_genders": {
    "label": "Targeting genders",
    "format": "array"
  },
  "targeting_by_country": {
    "label": "Targeting by country",
    "format": "array"
  },
  "targeting_interests": {
    "label": "Targeting interests",
    "format": "array"
  },
  "targeting_video_interactions": {
    "label": "Targeting video interactions",
    "format": "array"
  },
  "targeting_creator_interactions": {
    "label": "Targeting creator interactions",
    "format": "array"
  },
  "targeting_custom_audience": {
    "label": "Targeting custom audience",
    "format": "boolean"
  },
  "targeting_custom_audience_excluded": {
    "label": "Targeting custom audience excluded",
    "format": "boolean"
  },
  "targeting_countries": {
    "label": "Targeting countries",
    "format": "array"
  },
  "targeting_cities": {
    "label": "Targeting cities",
    "format": "array"
  },
  "targeting_provinces": {
    "label": "Targeting provinces",
    "format": "array"
  },
  "targeting_languages": {
    "label": "Targeting languages",
    "format": "array"
  },
  "targeting_devices": {
    "label": "Targeting devices",
    "format": "array"
  },
  "targeting_os": {
    "label": "Targeting os",
    "format": "array"
  },
  "targeting_spending_power": {
    "label": "Targeting spending power",
    "format": "array"
  },
  "video_views_bucket": {
    "label": "Video views bucket",
    "format": "string"
  },
  "video_views_min": {
    "label": "Video views min",
    "format": "integer"
  },
  "video_views_max": {
    "label": "Video views max",
    "format": "integer"
  },
  "rank": {
    "label": "Rank",
    "format": "integer"
  },
  "top_ads_country": {
    "label": "Top ads country",
    "format": "string"
  },
  "top_ads_period": {
    "label": "Top ads period",
    "format": "integer"
  },
  "ctr_top_percent": {
    "label": "CTR top %",
    "format": "number"
  },
  "likes": {
    "label": "Likes",
    "format": "integer"
  },
  "comments": {
    "label": "Comments",
    "format": "integer"
  },
  "shares": {
    "label": "Shares",
    "format": "integer"
  },
  "cost_level": {
    "label": "Cost level",
    "format": "integer"
  },
  "is_search_ad": {
    "label": "Is search ad",
    "format": "boolean"
  },
  "source": {
    "label": "Source",
    "format": "string"
  },
  "keyword_list": {
    "label": "Keyword list",
    "format": "array"
  },
  "pattern_labels": {
    "label": "Pattern labels",
    "format": "array"
  },
  "voice_over": {
    "label": "Voice over",
    "format": "boolean"
  },
  "highlight_text": {
    "label": "Highlight text",
    "format": "string"
  },
  "keyframes": {
    "label": "Keyframes",
    "format": "object"
  },
  "keyframe_highlights": {
    "label": "Keyframe highlights",
    "format": "object"
  },
  "percentiles": {
    "label": "Percentiles",
    "format": "object"
  },
  "copy_length": {
    "label": "Copy length",
    "format": "integer"
  },
  "text_language": {
    "label": "Text language",
    "format": "string"
  },
  "sentiment_score": {
    "label": "Sentiment score",
    "format": "number"
  },
  "analysis_angle": {
    "label": "Analysis angle",
    "format": "string"
  },
  "analysis_cta_intent": {
    "label": "Analysis CTA intent",
    "format": "string"
  },
  "analysis_tone": {
    "label": "Analysis tone",
    "format": "string"
  },
  "analysis_sentiment": {
    "label": "Analysis sentiment",
    "format": "number"
  },
  "analysis_offer_type": {
    "label": "Analysis offer type",
    "format": "string"
  },
  "analysis_funnel_stage": {
    "label": "Analysis funnel stage",
    "format": "string"
  },
  "analysis_confidence": {
    "label": "Analysis confidence",
    "format": "object"
  },
  "analysis_hook": {
    "label": "Analysis hook",
    "format": "string"
  },
  "analysis_offer": {
    "label": "Analysis offer",
    "format": "string"
  },
  "analysis_audience": {
    "label": "Analysis audience",
    "format": "string"
  },
  "analysis_strategy": {
    "label": "Analysis strategy",
    "format": "string"
  },
  "ad_ocr_text": {
    "label": "Image text",
    "format": "string"
  },
  "transcript": {
    "label": "Transcript",
    "format": "string"
  },
  "transcript_language": {
    "label": "Transcript language",
    "format": "string"
  },
  "hook_3s": {
    "label": "Hook (first 3 s)",
    "format": "string"
  },
  "speech_seconds": {
    "label": "Speech seconds",
    "format": "number"
  },
  "transcript_segments": {
    "label": "Transcript segments",
    "format": "array"
  },
  "media_files": {
    "label": "Media files",
    "format": "array"
  },
  "image_file_url": {
    "label": "Stored image",
    "format": "string"
  },
  "video_file_url": {
    "label": "Stored video",
    "format": "string"
  },
  "detail_status": {
    "label": "Detail status",
    "format": "string"
  },
  "matched_query": {
    "label": "Matched query",
    "format": "string"
  },
  "claimed_count": {
    "label": "Claimed count",
    "format": "integer"
  },
  "claimed_count_is_capped": {
    "label": "Claimed count is capped",
    "format": "boolean"
  },
  "scraped_at": {
    "label": "Scraped at",
    "format": "string"
  },
  "first_seen_at": {
    "label": "First seen",
    "format": "string"
  },
  "last_seen_at": {
    "label": "Last seen",
    "format": "string"
  },
  "ended_at": {
    "label": "Ended",
    "format": "string"
  },
  "times_seen": {
    "label": "Times seen",
    "format": "integer"
  },
  "previous_rank": {
    "label": "Previous rank",
    "format": "integer"
  },
  "change_type": {
    "label": "Change type",
    "format": "string"
  },
  "changed_fields": {
    "label": "Changed fields",
    "format": "array"
  },
  "run_tag": {
    "label": "Run tag",
    "format": "string"
  },
  "search_query": {
    "label": "Search page",
    "format": "string"
  },
  "has_ads": {
    "label": "Has ads",
    "format": "boolean"
  },
  "exact_name_match": {
    "label": "Exact name match",
    "format": "boolean"
  },
  "report_country_share": {
    "label": "Report country share",
    "format": "array"
  },
  "report_ads_published_by_month": {
    "label": "Report ads published by month",
    "format": "array"
  },
  "report_ads_published": {
    "label": "Report ads published",
    "format": "integer"
  },
  "report_first_published": {
    "label": "Report first published",
    "format": "string"
  },
  "report_last_published": {
    "label": "Report last published",
    "format": "string"
  },
  "summary_ad_count": {
    "label": "Summary ad count",
    "format": "integer"
  },
  "summary_active_count": {
    "label": "Summary active count",
    "format": "integer"
  },
  "summary_removed_count": {
    "label": "Summary removed count",
    "format": "integer"
  },
  "summary_longest_days": {
    "label": "Summary longest days",
    "format": "integer"
  },
  "summary_formats": {
    "label": "Summary formats",
    "format": "array"
  },
  "summary_landing_domains": {
    "label": "Summary landing domains",
    "format": "array"
  },
  "summary_countries": {
    "label": "Summary countries",
    "format": "array"
  },
  "summary_distinct_copies": {
    "label": "Summary distinct copies",
    "format": "integer"
  },
  "summary_ad_ids": {
    "label": "Summary ad ids",
    "format": "array"
  },
  "summary_advertisers": {
    "label": "Summary advertisers",
    "format": "array"
  }
}
```

## About this Actor

This example demonstrates how to use [TikTok Ads Library Scraper — TikTok Creative Center Top Ads](https://apify.com/hyperbach/tiktok-ad-library-scraper.md) with a specific input configuration. Visit the [Actor detail page](https://apify.com/hyperbach/tiktok-ad-library-scraper.md) to learn more, explore other use cases, and run it yourself.


## How to integrate an Actor?

This Task's input is already configured above. Use it as-is rather than inventing a new one.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For full API examples (JavaScript, Python, CLI, MCP, OpenAPI), see this Task's Actor page: https://apify.com/hyperbach/tiktok-ad-library-scraper.md

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).