Update Settings
curl --request POST \
--url https://api.lobstr.io/v1/squids/{squid_hash} \
--header 'Authorization: <authorization>' \
--header 'Content-Type: <content-type>'import requests
url = "https://api.lobstr.io/v1/squids/{squid_hash}"
headers = {
"Authorization": "<authorization>",
"Content-Type": "<content-type>"
}
response = requests.post(url, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'}
};
fetch('https://api.lobstr.io/v1/squids/{squid_hash}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.lobstr.io/v1/squids/{squid_hash}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: <content-type>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.lobstr.io/v1/squids/{squid_hash}"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("Content-Type", "<content-type>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.lobstr.io/v1/squids/{squid_hash}")
.header("Authorization", "<authorization>")
.header("Content-Type", "<content-type>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.lobstr.io/v1/squids/{squid_hash}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
response = http.request(request)
puts response.read_bodyTikTok Top Ads Scraper
Update Settings
Configure the TikTok Top Ads Scraper parameters
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>'import requests
url = "https://api.lobstr.io/v1/squids/{squid_hash}"
headers = {
"Authorization": "<authorization>",
"Content-Type": "<content-type>"
}
response = requests.post(url, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'}
};
fetch('https://api.lobstr.io/v1/squids/{squid_hash}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.lobstr.io/v1/squids/{squid_hash}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: <content-type>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.lobstr.io/v1/squids/{squid_hash}"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("Content-Type", "<content-type>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.lobstr.io/v1/squids/{squid_hash}")
.header("Authorization", "<authorization>")
.header("Content-Type", "<content-type>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.lobstr.io/v1/squids/{squid_hash}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
response = http.request(request)
puts response.read_bodyConfigure the scraper parameters to control how TikTok ads are filtered and sorted. These settings determine region, industry, objective, and other filtering criteria.
Headers
string
required
Your API authentication token. Value:
Token YOUR_API_KEYstring
required
Request body format. Value:
application/jsonScraper Parameters
Set these parameters in theparams 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, VietnamAvailable 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 & TransportationUse
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
}
}
}'
import requests
API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.lobstr.io/v1"
headers = {"Authorization": f"Token {API_KEY}"}
squid_id = "YOUR_SQUID_HASH"
# Update scraper settings
response = requests.post(f"{BASE_URL}/squids/{squid_id}",
headers=headers,
json={
"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 # Enable for full ad details (1 credit per ad)
}
}
}
)
data = response.json()
print(f"Settings updated: {data['name']}")
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
}
}
}