Skip to content
Examples

Update Settings

Configure the TikTok Top Ads Scraper parameters

The v1 API, for batchesSquids, tasks and runs: many calls on a schedule, delivered where you work. For one call that answers in seconds, use the API v2.
POSThttps://api.lobstr.io/v1/squids/{squid_hash}

Configure the scraper parameters to control how TikTok ads are filtered and sorted. These settings determine region, industry, objective, and other filtering criteria.

Headers

Authorizationstringheaderrequired

Your API authentication token. Value: Token YOUR_API_KEY

Content-Typestringheaderrequired

Request body format. Value: application/json

Scraper Parameters

Set these parameters in the params object:

Parameter Type Default Description
region string World Specify a predetermined region for your search (e.g., United States, France, Germany)
industry string All industries Filter by industry (e.g., Beauty & Personal Care, Games, E-Commerce (Non-app))
objective string All objectives Campaign objective filter: Conversions, Lead Generation, Traffic, Video Views, etc.
like string All likes Filter by engagement percentile: Top 1~20%, Top 21~40%, etc.
time_range string Last 7 days Ad publication period: Last 7 days, Last 30 days, Last 180 days
sort_by string For You Sorting option: For You, Reach, CTY, 2s Views Rate, 6s Views Rate
functions.ad_details boolean false Fetch full ad details including landing page URL and additional metadata (1 credit per ad)

Available Regions

World, Argentina, Australia, Austria, Bahrain, Belarus, Belgium, Brazil, Cambodia, Canada, Chile, Colombia, Czechia, Denmark, Ecuador, Egypt, Finland, France, Germany, Greece, Hungary, Indonesia, Iraq, Ireland, Israel, Italy, Japan, Jordan, Kazakhstan, Kuwait, Lebanon, Malaysia, Mexico, Morocco, Netherlands, New Zealand, Norway, Oman, Pakistan, Peru, Philippines, Poland, Portugal, Qatar, Romania, Saudi Arabia, Singapore, South Africa, South Korea, Spain, Sweden, Switzerland, Taiwan, Thailand, Turkey, United Arab Emirates, United Kingdom, United States, Uruguay, Vietnam

Available Industries

All industries, App Installs, 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

Use sort_by: Reach to find ads with the highest audience reach for competitive analysis.

Filter by like: Top 1~20% to see only the most engaging ads.

Combining industry and objective filters helps narrow down ads most relevant to your use case.

Code Examples

curl -X POST "https://api.lobstr.io/v1/squids/YOUR_SQUID_HASH" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TikTok Top Ads Scraper (1)",
    "concurrency": 1,
    "export_unique_results": true,
    "to_complete": false,
    "no_line_breaks": true,
    "params": {
      "region": "United States",
      "industry": "Beauty & Personal Care",
      "objective": "Conversions",
      "like": "Top 1~20%",
      "time_range": "Last 30 days",
      "sort_by": "Reach",
      "functions": {
        "ad_details": false
      }
    }
  }'

Response

201
{
  "name": "TikTok Top Ads Scraper (1)",
  "concurrency": 1,
  "export_unique_results": true,
  "to_complete": false,
  "no_line_breaks": true,
  "params": {
    "region": "United States",
    "industry": "Beauty & Personal Care",
    "objective": "Conversions",
    "like": "Top 1~20%",
    "time_range": "Last 30 days",
    "sort_by": "Reach",
    "functions": {
      "ad_details": false
    }
  }
}