Skip to main content
POST
/
v1
/
squids
/
{squid_hash}
Update Settings
curl --request POST \
  --url https://api.lobstr.io/v1/squids/{squid_hash} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>'

Documentation Index

Fetch the complete documentation index at: https://docs.lobstr.io/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Headers

​
Authorization
string
required
Your API authentication token. Value: Token YOUR_API_KEY
​
Content-Type
string
required
Request body format. Value: application/json

​
Scraper Parameters

Set these parameters in the params object:
ParameterTypeDefaultDescription
regionstringWorldSpecify a predetermined region for your search (e.g., United States, France, Germany)
industrystringAll industriesFilter by industry (e.g., Beauty & Personal Care, Games, E-Commerce (Non-app))
objectivestringAll objectivesCampaign objective filter: Conversions, Lead Generation, Traffic, Video Views, etc.
likestringAll likesFilter by engagement percentile: Top 1~20%, Top 21~40%, etc.
time_rangestringLast 7 daysAd publication period: Last 7 days, Last 30 days, Last 180 days
sort_bystringFor YouSorting option: For You, Reach, CTY, 2s Views Rate, 6s Views Rate
functions.ad_detailsbooleanfalseFetch 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
    }
  }
}