{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Ads Scraper: Ad Library & Top Ads",
    "description": "See the TikTok ads any brand runs: ad videos, ad text, landing pages, dates, reach and targeting from the TikTok Ad Library (Europe, UK, Turkey, Brazil), plus the best-performing Top Ads with CTR and likes for the US and 27 more countries. No login.",
    "version": "1.0",
    "x-build-id": "ZU3KXFwBSj3KorXoS"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/panix~tiktok-ads-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-panix-tiktok-ads-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/panix~tiktok-ads-scraper/runs": {
      "post": {
        "operationId": "runs-sync-panix-tiktok-ads-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/panix~tiktok-ads-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-panix-tiktok-ads-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "mode": {
            "title": "What to scrape",
            "enum": [
              "adLibrary",
              "topAds"
            ],
            "type": "string",
            "description": "Ad Library: every ad a brand or keyword ran in Europe, the UK, Switzerland, Turkey or Brazil, with targeting, reach per country, landing page and advertiser details. Top Ads: TikTok's list of best-performing ads (Creative Center) for the US and 27 more countries, with CTR, likes, budget level and video analytics.",
            "default": "adLibrary"
          },
          "searchTerms": {
            "title": "Search terms (Ad Library)",
            "type": "array",
            "description": "Brand names, advertiser names or words in the ad text, e.g. nike or skincare. Put a term in double quotes for an exact phrase (\"air max\"). Each term runs once per country.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Links or ad IDs",
            "type": "array",
            "description": "Ad Library search or ad links (library.tiktok.com), Creative Center Top Ad links, or ad IDs. Filters inside a search link are used. Single ads always include their details.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "searchType": {
            "title": "Search by (Ad Library)",
            "enum": [
              "all",
              "advertiser",
              "keyword"
            ],
            "type": "string",
            "description": "Everything: advertiser name or ad text. Advertiser: finds the advertiser accounts named like the term and returns all their ads. Ad text: only ads whose text contains the term.",
            "default": "all"
          },
          "countries": {
            "title": "Countries (Ad Library)",
            "type": "array",
            "description": "Countries where the ads were shown. The Ad Library covers the EU, EEA, UK, Switzerland, Turkey and Brazil (no US: use Top Ads for US ads). ALL searches all 34. Empty = France.",
            "items": {
              "type": "string",
              "enum": [
                "ALL",
                "AT",
                "BE",
                "BR",
                "BG",
                "HR",
                "CY",
                "CZ",
                "DK",
                "EE",
                "FI",
                "FR",
                "DE",
                "GR",
                "HU",
                "IS",
                "IE",
                "IT",
                "LV",
                "LI",
                "LT",
                "LU",
                "MT",
                "NL",
                "NO",
                "PL",
                "PT",
                "RO",
                "SK",
                "SI",
                "ES",
                "SE",
                "CH",
                "TR",
                "GB"
              ],
              "enumTitles": [
                "All 34 countries",
                "Austria (AT)",
                "Belgium (BE)",
                "Brazil (BR)",
                "Bulgaria (BG)",
                "Croatia (HR)",
                "Cyprus (CY)",
                "Czech Republic (CZ)",
                "Denmark (DK)",
                "Estonia (EE)",
                "Finland (FI)",
                "France (FR)",
                "Germany (DE)",
                "Greece (GR)",
                "Hungary (HU)",
                "Iceland (IS)",
                "Ireland (IE)",
                "Italy (IT)",
                "Latvia (LV)",
                "Liechtenstein (LI)",
                "Lithuania (LT)",
                "Luxembourg (LU)",
                "Malta (MT)",
                "Netherlands (NL)",
                "Norway (NO)",
                "Poland (PL)",
                "Portugal (PT)",
                "Romania (RO)",
                "Slovak (SK)",
                "Slovenia (SI)",
                "Spain (ES)",
                "Sweden (SE)",
                "Switzerland (CH)",
                "Turkey (TR)",
                "United Kingdom (GB)"
              ]
            }
          },
          "startDate": {
            "title": "Shown on or after (Ad Library)",
            "type": "string",
            "description": "Only ads shown on or after this date: 2026-10-01, or a period such as '30 days'. Empty = the last 12 months."
          },
          "endDate": {
            "title": "Shown on or before (Ad Library)",
            "type": "string",
            "description": "Only ads shown on or before this date. Empty = today."
          },
          "adStatus": {
            "title": "Ad status",
            "enum": [
              "all",
              "active",
              "inactive"
            ],
            "type": "string",
            "description": "Active: ads still running. Inactive: ads that stopped.",
            "default": "all"
          },
          "adFormat": {
            "title": "Ad format",
            "enum": [
              "all",
              "video",
              "image"
            ],
            "type": "string",
            "description": "Video or image ads only.",
            "default": "all"
          },
          "targetGender": {
            "title": "Targeted gender",
            "enum": [
              "all",
              "female",
              "male"
            ],
            "type": "string",
            "description": "Only ads targeted at this gender.",
            "default": "all"
          },
          "targetAges": {
            "title": "Targeted ages",
            "type": "array",
            "description": "Only ads targeted at these age groups. Empty = all ages.",
            "items": {
              "type": "string",
              "enum": [
                "13-17",
                "18-24",
                "25-34",
                "35-44",
                "45-54",
                "55+"
              ]
            }
          },
          "uniqueReach": {
            "title": "Unique reach",
            "type": "array",
            "description": "Only ads that reached this many unique users. Empty = any reach.",
            "items": {
              "type": "string",
              "enum": [
                "0-10K",
                "10K-100K",
                "100K+"
              ],
              "enumTitles": [
                "Under 10K",
                "10K to 100K",
                "Over 100K"
              ]
            }
          },
          "sortBy": {
            "title": "Sort by",
            "enum": [
              "newest",
              "oldest",
              "newestFirstShown",
              "oldestFirstShown",
              "mostReach",
              "leastReach"
            ],
            "type": "string",
            "description": "Order of the Ad Library results. TikTok ranks keyword searches by relevance first.",
            "default": "newest"
          },
          "includeAudienceBreakdown": {
            "title": "Add reach by country, age and gender",
            "type": "boolean",
            "description": "Adds a reachBreakdown list with the unique reach for every country, age group and gender (EU transparency data). Comes with ad details at no extra cost; makes rows larger.",
            "default": false
          },
          "topAdsCountries": {
            "title": "Countries (Top Ads)",
            "type": "array",
            "description": "Countries for TikTok's Top Ads list. ALL = TikTok's all-regions list. Empty = United States.",
            "items": {
              "type": "string",
              "enum": [
                "ALL",
                "AR",
                "AU",
                "BR",
                "CA",
                "CO",
                "FR",
                "DE",
                "ID",
                "IT",
                "JP",
                "MY",
                "MX",
                "NL",
                "PK",
                "PH",
                "RO",
                "SA",
                "SG",
                "ZA",
                "KR",
                "ES",
                "SE",
                "TH",
                "TR",
                "AE",
                "GB",
                "US",
                "VN"
              ],
              "enumTitles": [
                "All regions",
                "Argentina (AR)",
                "Australia (AU)",
                "Brazil (BR)",
                "Canada (CA)",
                "Colombia (CO)",
                "France (FR)",
                "Germany (DE)",
                "Indonesia (ID)",
                "Italy (IT)",
                "Japan (JP)",
                "Malaysia (MY)",
                "Mexico (MX)",
                "Netherlands (NL)",
                "Pakistan (PK)",
                "Philippines (PH)",
                "Romania (RO)",
                "Saudi Arabia (SA)",
                "Singapore (SG)",
                "South Africa (ZA)",
                "South Korea (KR)",
                "Spain (ES)",
                "Sweden (SE)",
                "Thailand (TH)",
                "Turkey (TR)",
                "United Arab Emirates (AE)",
                "United Kingdom (GB)",
                "United States (US)",
                "Vietnam (VN)"
              ]
            }
          },
          "topAdsPeriod": {
            "title": "Period (Top Ads)",
            "enum": [
              "7",
              "30",
              "180"
            ],
            "type": "string",
            "description": "Top ads of the last 7, 30 or 180 days.",
            "default": "30"
          },
          "topAdsIndustries": {
            "title": "Industries (Top Ads)",
            "type": "array",
            "description": "Only top ads from these industries. Empty = all industries.",
            "items": {
              "type": "string",
              "enum": [
                "Apparel & Accessories",
                "Appliances",
                "Apps",
                "Baby, Kids & Maternity",
                "Beauty & Personal Care",
                "Business Services",
                "E-Commerce (Non-app)",
                "Education",
                "Financial Services",
                "Food & Beverage",
                "Games",
                "Health",
                "Home Improvement",
                "Household Products",
                "Life Services",
                "News & Entertainment",
                "Pets",
                "Sports & Outdoor",
                "Tech & Electronics",
                "Travel",
                "Vehicle & Transportation"
              ]
            }
          },
          "topAdsObjectives": {
            "title": "Campaign objectives (Top Ads)",
            "type": "array",
            "description": "Only top ads with these campaign objectives. Empty = all.",
            "items": {
              "type": "string",
              "enum": [
                "traffic",
                "app_install",
                "conversion",
                "video_view",
                "reach",
                "lead_generation",
                "product_sales",
                "app_promotion"
              ],
              "enumTitles": [
                "Traffic",
                "App Installs",
                "Conversions",
                "Video Views",
                "Reach",
                "Lead Generation",
                "Product sales",
                "App promotion"
              ]
            }
          },
          "topAdsLanguages": {
            "title": "Ad languages (Top Ads)",
            "type": "array",
            "description": "Only top ads in these languages. Empty = all.",
            "items": {
              "type": "string",
              "enum": [
                "en",
                "es",
                "ar",
                "vi",
                "th",
                "de",
                "id",
                "pt",
                "fr",
                "ms",
                "nl",
                "ja",
                "it",
                "ro",
                "zh-Hant",
                "ko"
              ],
              "enumTitles": [
                "English",
                "Spanish",
                "Arabic",
                "Vietnamese",
                "Thai",
                "German",
                "Indonesian",
                "Portuguese",
                "French",
                "Malay",
                "Dutch",
                "Japanese",
                "Italian",
                "Romanian",
                "Chinese (Traditional)",
                "Korean"
              ]
            }
          },
          "topAdsSortBy": {
            "title": "Sort by (Top Ads)",
            "enum": [
              "for_you",
              "impression",
              "ctr",
              "cvr",
              "like",
              "play_2s_rate",
              "play_6s_rate"
            ],
            "type": "string",
            "description": "The ranking TikTok uses for the list.",
            "default": "for_you"
          },
          "topAdsKeywords": {
            "title": "Keywords in ad text (Top Ads)",
            "type": "array",
            "description": "Keep only top ads whose text or brand name contains one of these words. TikTok offers keyword search only to logged-in users, so the Actor scans the list and filters it. Ads left out are free.",
            "items": {
              "type": "string"
            }
          },
          "expandTopAds": {
            "title": "Get more than 20 top ads per country",
            "type": "boolean",
            "description": "Without a login TikTok shows 20 top ads per filter. With this on, the Actor also asks per industry, objective and ranking and merges the answers (duplicates removed), up to the full list TikTok has for the country and period.",
            "default": true
          },
          "includeAnalytics": {
            "title": "Add video analytics (Top Ads)",
            "type": "boolean",
            "description": "Second-by-second viewer retention and click curves, plus how the ad ranks against other ads for CTR, conversion rate, impressions and clicks (percentiles). Charged per ad with analytics.",
            "default": false
          },
          "maxAdsPerSource": {
            "title": "Max ads per search",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "How many ads to collect for each search term and country (Ad Library) or each country (Top Ads).",
            "default": 100
          },
          "maxResults": {
            "title": "Maximum ads in total",
            "minimum": 1,
            "maximum": 10000000,
            "type": "integer",
            "description": "Stop after this many ads across all searches. Empty = no total limit."
          },
          "includeDetails": {
            "title": "Add ad details",
            "type": "boolean",
            "description": "Ad Library: landing page, call to action, objective, advertiser ID, country and TikTok account, who paid, targeting (countries, ages, gender, audience size, interests) and reach per country. Top Ads: landing page, comments, shares, keywords and countries. Charged per ad with details; failed lookups are free.",
            "default": true
          },
          "maxAdvertisersPerTerm": {
            "title": "Max advertiser accounts per name",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "With Search by = Advertiser name, a name can match several accounts (countries, resellers). The closest names are used first.",
            "default": 3
          },
          "onlyNewAds": {
            "title": "Only new ads (monitoring)",
            "type": "boolean",
            "description": "Remember the ads of every search and deliver only ads not seen before. Schedule the run daily or weekly to get new competitor ads.",
            "default": false
          },
          "watchlistName": {
            "title": "Watchlist name",
            "type": "string",
            "description": "Keeps separate memories for different monitoring tasks (letters, digits, - and _).",
            "default": "default"
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Apify datacenter proxy works well. Every Ad Library request uses a fresh IP.",
            "default": {
              "useApifyProxy": true
            }
          },
          "maxConcurrency": {
            "title": "Parallel requests",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "How many requests run at the same time.",
            "default": 8
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}