Skip to main content
GET
/
v1
/
scrape
/
tiktok-ad-library
/
search
Search Top Ads
curl --request GET \
  --url https://api.sociavault.com/v1/scrape/tiktok-ad-library/search \
  --header 'X-API-Key: <api-key>'
{
  "success": true,
  "data": {
    "success": true,
    "query": "shoes",
    "region": "US",
    "period": 30,
    "ads": {
      "0": {
        "ad_title": "HR would like to remind you that what happens at the premiere, stays at the premiere. Office Romance June 5 on @Netflix ",
        "brand_name": "",
        "cost": 1,
        "ctr": 0.34,
        "favorite": false,
        "id": "7645249124891607041",
        "industry_key": "label_23108000000",
        "is_search": false,
        "like": 1294,
        "objective_key": "campaign_objective_traffic",
        "video_info": {
          "vid": "v15044gf0000d8blg3vog65m7i2j3320",
          "duration": 55.843,
          "cover": "https://p16-common-sign.tiktokcdn.com/tos-maliva-p-0068c799-us/owWoFXnfIfGLjgWAuAYQXIeqGAQpGQGYReBQGU~tplv-noop.image?dr=18692&refresh_token=25085a08&x-expires=1781236812&x-signature=cYE54g9ru2lGz4QwxLNrzJR7vao%3D&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=317596d8&idc=my&VideoID=v15044gf0000d8blg3vog65m7i2j3320",
          "video_url": {
            "540p": "https://v16m-default.tiktokcdn.com/4cf48674533ea486264fecb0e62bb0d8/6a2b844c/video/tos/maliva/tos-maliva-ve-0068c799-us/osXAIFIWHpGGG8AGAefjLRXQeYUgUoIRWpQfQ3/?a=0&bti=NTU4QDM1NGA%3D&&bt=511&ft=cApXJCz7ThWHE.t9LGZmo0P&mime_type=video_mp4&rc=M2Q7ZDVpODY8NjhpOjk4ZkBpMzZtbHA5cjZvOzMzaTczNEBeLl9fYl4tXzUxNDNiMC40YSMvMC80MmRzZF9hLS1kMTJzcw%3D%3D&vvpl=1&l=202606120559171BEEA8ABD2CB799CFAAE&btag=e00088000",
            "720p": "https://v16m-default.tiktokcdn.com/1834a0d6d95854f01ac31c062a0d579e/6a2b844c/video/tos/maliva/tos-maliva-ve-0068c799-us/ocf1SxIUCtBCUXsiEWiwHIRIiEJIEAA26jQqPA/?a=0&bti=NTU4QDM1NGA%3D&&bt=1360&ft=cApXJCz7ThWHE.t9LGZmo0P&mime_type=video_mp4&rc=Z2U2OWRlOzw8aTY4aGY5ZUBpMzZtbHA5cjZvOzMzaTczNEAyMi80YzQ1XzAxX2AyYTA1YSMvMC80MmRzZF9hLS1kMTJzcw%3D%3D&vvpl=1&l=202606120559171BEEA8ABD2CB799CFAAE&btag=e00088000"
          },
          "width": 720,
          "height": 1280
        }
      },
      "1": {
        "ad_title": "إعلان لا يفوتكم خصومات 30% ثابت في سكتشرز خصومات سكتشرز تناسب كل العائله Skechers #سكتشرز #عروض #خصومات ",
        "brand_name": "",
        "cost": 0,
        "ctr": 0.9,
        "favorite": false,
        "id": "7639391345481367572",
        "industry_key": "label_22111000000",
        "is_search": false,
        "like": 861,
        "objective_key": "campaign_objective_video_view",
        "video_info": {
          "vid": "v1c044g50000d80tnmvog65kkmu4l21g",
          "duration": 46.7,
          "cover": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0037/oUDDlcQbQBVAiQEeBfRuEQpBgvhGdgE3ISA3Fq~tplv-noop.image?dr=18692&refresh_token=a0b1868e&x-expires=1781236803&x-signature=w%2Bd3QIBeS8eKmuX3vyfWIUc%2BuCE%3D&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=317596d8&idc=my&VideoID=v1c044g50000d80tnmvog65kkmu4l21g",
          "video_url": {
            "720p": "https://v16m-default.tiktokcdn.com/2d7e28bd73853680e127bc1be7dc1eb5/6a2b8443/video/tos/alisg/tos-alisg-pve-0037c001/oUb3IQLD1oAliixBA0iiw3BtCAAIWBTEIpfKuO/?a=0&bti=NTU4QDM1NGA%3D&&bt=1983&ft=cApXJCz7ThWHE.t9LGZmo0P&mime_type=video_mp4&rc=NGVoOjw5Ojs5PGQ8PDw4NkBpajU3cG45cnB3OzMzODczNEBjYTRfXjEtNjMxXjEzLWBeYSMuaXJoMmRzay1hLS1kMWBzcw%3D%3D&vvpl=1&l=202606120559171BEEA8ABD2CB799CFAAE&btag=e00088000"
          },
          "width": 576,
          "height": 1024
        }
      }
    },
    "pagination": {
      "has_more": false,
      "page": 1,
      "size": 20,
      "total_count": 4
    },
    "total": 4,
    "has_more": false,
    "cursor": null
  },
  "credits_used": 1
}
💳 1 credit per request

Authorizations

​
X-API-Key
string
header
required

API key for authentication. Format: sk_live_xxxxxxxxxxxxx

Get your API key from the Dashboard.

Query Parameters

​
region
enum<string>
default:US

Country code. Defaults to US.

Available options:
DZ,
AR,
AU,
AT,
AZ,
BH,
BD,
BY,
BE,
BO,
BR,
BG,
KH,
CA,
CL,
CO,
CR,
HR,
CY,
CZ,
DK,
DO,
EC,
EG,
EE,
FI,
FR,
DE,
GR,
GT,
JO,
HU,
ID,
IQ,
IE,
IL,
IT,
JP,
KZ,
KE,
KW,
LV,
LB,
MY,
MX,
MA,
NL,
NZ,
NG,
NO,
OM,
PK,
PA,
PY,
PE,
PH,
PL,
PT,
PR,
QA,
LT,
RO,
SA,
RS,
SG,
SK,
SI,
ZA,
KR,
ES,
LK,
SE,
CH,
TW,
TH,
TR,
AE,
GB,
US,
UY,
VN
Example:

"US"

​
period
enum<string>

Time window for Top Ads (in days).

Available options:
7,
30,
180
Example:

"30"

​
query
string

Optional keyword to search ad titles/content.

Example:

"spotify"

​
order_by
enum<string>
default:for_you

Sort metric. Defaults to for_you.

Available options:
for_you,
impression,
play_2s_rate,
play_6s_rate,
cvr,
ctr,
like
Example:

"for_you"

​
industry
enum<string>

Industry filter.

Available options:
apparel_accessories,
appliances,
apps,
baby_kids_maternity,
beauty_personal_care,
business_services,
ecommerce_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
Example:

"beauty_personal_care"

​
objective
enum<string>

Campaign objective filter.

Available options:
app_installs,
conversions,
lead_generation,
product_sales,
reach,
traffic,
video_views
Example:

"traffic"

​
duration
enum<string>

Video duration filter.

Available options:
under_10s,
10_20s,
20_30s,
30_40s,
40_50s,
over_50s
Example:

"under_10s"

​
likes
enum<string>

Likes percentile filter.

Available options:
top_1_20,
top_21_40,
top_41_60,
top_61_80,
top_81_100
Example:

"top_1_20"

​
ad_format
enum<string>

Ad format filter.

Available options:
spark_ads,
non_spark_ads
Example:

"spark_ads"

​
ad_language
enum<string>

Ad language filter.

Available options:
en,
es,
ar,
vi,
th,
de,
id,
pt,
fr,
ms,
nl,
ja,
it,
ro,
zh-Hant,
ko
Example:

"en"

​
cursor
integer

Page number to fetch. Use the cursor returned from the previous response, like 3 for page 3.

Example:

3

​
limit
integer

Number of ads to return, max 50. Defaults to 20.

Example:

20

Response

Successful response containing top ads

Key Response Fields:

  • query: The search keyword used
  • region: Region code applied to the search
  • period: Time window in days
  • ads[].id: Unique ad ID
  • ads[].ad_title: Ad creative text/caption
  • ads[].brand_name: Brand name (if available)
  • ads[].ctr: Click-through rate
  • ads[].like: Total likes on the ad
  • ads[].cost: Credit cost indicator
  • ads[].industry_key: Industry category identifier
  • ads[].objective_key: Campaign objective (e.g. "campaign_objective_traffic")
  • ads[].video_info.duration: Video length in seconds
  • ads[].video_info.cover: Video cover/thumbnail URL
  • ads[].video_info.video_url: Download URLs by quality (540p, 720p)
  • ads[].video_info.width: Video width in pixels
  • ads[].video_info.height: Video height in pixels
  • pagination.has_more: Whether more pages are available
  • pagination.page: Current page number
  • pagination.total_count: Total number of matching ads
  • total: Total ads returned
  • has_more: Whether more pages exist
  • cursor: Cursor value for the next page (null if last page)