Get Ad Details
curl --request GET \
--url https://api.sociavault.com/v1/scrape/tiktok-ad-library/ad \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.sociavault.com/v1/scrape/tiktok-ad-library/ad"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.sociavault.com/v1/scrape/tiktok-ad-library/ad', 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.sociavault.com/v1/scrape/tiktok-ad-library/ad",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$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.sociavault.com/v1/scrape/tiktok-ad-library/ad"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.sociavault.com/v1/scrape/tiktok-ad-library/ad")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sociavault.com/v1/scrape/tiktok-ad-library/ad")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"success": true,
"ad_title": "Selbst der Feuergigant staunt über diese Heißluftfritteuse!",
"brand_name": "EC JEWELRY TRADING CO., LIMITED",
"adv_biz_ids": "7650399223921442817",
"tt_user": null,
"comment": null,
"cost": null,
"country_code": {
"0": "DE"
},
"ctr": null,
"favorite": false,
"has_summary": false,
"highlight_text": "",
"id": "1881677718950002",
"industry_key": null,
"is_search": false,
"keyword_list": null,
"landing_page": "https://tryeloura.eu.cc/products/air-fryer-5-5l?utm_source=tiktok&utm_id=__CAMPAIGN_ID__&utm_campaign=__CAMPAIGN_NAME__&utm_medium=paid",
"estimated_audience": "0-1K",
"location": {
"total_region": 1,
"total_impressions": "0-1K",
"data": {
"0": {
"region": "DE",
"impressions": "0-1K",
"breakdowns": {
"0": {
"age": "13-17",
"gender": "MALE",
"impressions": "0-1K"
},
"1": {
"age": "13-17",
"gender": "FEMALE",
"impressions": "0-1K"
},
"2": {
"age": "13-17",
"gender": "UNKNOWN",
"impressions": "0-1K"
},
"3": {
"age": "18-24",
"gender": "MALE",
"impressions": "0-1K"
},
"4": {
"age": "18-24",
"gender": "FEMALE",
"impressions": "0-1K"
},
"5": {
"age": "18-24",
"gender": "UNKNOWN",
"impressions": "0-1K"
},
"6": {
"age": "25-34",
"gender": "MALE",
"impressions": "0-1K"
},
"7": {
"age": "25-34",
"gender": "FEMALE",
"impressions": "0-1K"
},
"8": {
"age": "25-34",
"gender": "UNKNOWN",
"impressions": "0-1K"
},
"9": {
"age": "35-44",
"gender": "MALE",
"impressions": "0-1K"
},
"10": {
"age": "35-44",
"gender": "FEMALE",
"impressions": "0-1K"
},
"11": {
"age": "35-44",
"gender": "UNKNOWN",
"impressions": "0-1K"
},
"12": {
"age": "45-54",
"gender": "MALE",
"impressions": "0-1K"
},
"13": {
"age": "45-54",
"gender": "FEMALE",
"impressions": "0-1K"
},
"14": {
"age": "45-54",
"gender": "UNKNOWN",
"impressions": "0-1K"
},
"15": {
"age": "55+",
"gender": "MALE",
"impressions": "0-1K"
},
"16": {
"age": "55+",
"gender": "FEMALE",
"impressions": "0-1K"
},
"17": {
"age": "55+",
"gender": "UNKNOWN",
"impressions": "0-1K"
}
}
}
}
},
"like": null,
"objective_key": "Sales",
"objectives": {
"0": {
"label": "Sales",
"value": null
}
},
"pattern_label": {},
"share": null,
"source": "TikTok Ads Library",
"source_key": null,
"video_info": {
"vid": null,
"duration": null,
"cover": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o4Kb26EvNEmOWrgxGyVy6zAIDfAeFDBv3C0VfQ~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=fa083994&x-expires=1794960000&x-signature=%2BTL7AFpNJVwcnCEyaiClPjzA9IQ%3D&t=4d5b0474&ps=13740610&shp=0c75dd76&shcp=9b759fb9&idc=sg1",
"video_url": {
"720p": "https://library.tiktok.com/api/v1/cdn/1794941926/video/aHR0cHM6Ly92MTZtLnRpa3Rva2Nkbi5jb20vMzY3ODI4ZjJkMmM3ZjBmOThjZTYyMTg0OGQ5OTFmYTAvNmFmY2Y4NTUvdmlkZW8vdG9zL2FsaXNnL3Rvcy1hbGlzZy12ZS0wMDUxYzAwMS1zZy9vQUJ2N3ZCeklaaVRBNzFBR1gxOVk5aVVCY1FZM1hPQTNFYUpsLw==/26e31dff-edcd-4ca7-b2b3-dc4e2b317bac?a=475769&bt=744&btag=e000b8000&bti=PDU2NmYwMy86&ft=.NpOcInz7ThtrjxGXq8Zmo&l=2026111802584641B1253AD4E2C55CD894&mime_type=video_mp4&rc=PGg2OmU1Ojo3ZThoNTo6N0BpMzVqOnM5cmh5ZTMzODYzNEA2XmAzLTYwNmMxYl5gMzQuYSMtcC1kMmQ0Ym5hLS1kMDFzcw%3D%3D&signature=k0RhRWTTZ%2FjVL%2BVmjchX%2BMPwFj7fyo0wEechWmW48lE%3D&vvpl=1"
},
"width": null,
"height": null
},
"voice_over": null,
"creative_center_url": null,
"detail_analysis": null,
"interactive_time_analysis": {},
"recommended_for_you": {},
"audit_status": "1",
"sor_audit_status": "1",
"rejection_info": null,
"is_unavailable": false,
"first_shown_date": 1794441600000,
"last_shown_date": 1794528000000,
"image_urls": {
"0": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o4Kb26EvNEmOWrgxGyVy6zAIDfAeFDBv3C0VfQ~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=fa083994&x-expires=1794960000&x-signature=%2BTL7AFpNJVwcnCEyaiClPjzA9IQ%3D&t=4d5b0474&ps=13740610&shp=0c75dd76&shcp=9b759fb9&idc=sg1"
},
"type": "2"
},
"credits_used": 1
}{
"success": false,
"error": "ad_id parameter is required"
}{
"success": false,
"error": "User not authenticated"
}{
"success": false,
"error": "Insufficient credits",
"required": 1,
"available": 0
}TikTok Ad Library
Get Ad Details
Get the full record for one TikTok ad. Pass an id from Search Ads, a library.tiktok.com ad URL, or a Creative Center Top Ads ID.
Credit Cost: 1 credit per request
Ads from the public Ads Library include the countries they were shown in (country_code, and location with impression ranges by age and gender), the audience range (estimated_audience) and the dates they were first and last shown (first_shown_date and last_shown_date, in milliseconds). Metrics only the Creative Center has, such as ctr, like and share, are null for these ads.
GET
/
v1
/
scrape
/
tiktok-ad-library
/
ad
Get Ad Details
curl --request GET \
--url https://api.sociavault.com/v1/scrape/tiktok-ad-library/ad \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.sociavault.com/v1/scrape/tiktok-ad-library/ad"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.sociavault.com/v1/scrape/tiktok-ad-library/ad', 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.sociavault.com/v1/scrape/tiktok-ad-library/ad",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$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.sociavault.com/v1/scrape/tiktok-ad-library/ad"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.sociavault.com/v1/scrape/tiktok-ad-library/ad")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sociavault.com/v1/scrape/tiktok-ad-library/ad")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"success": true,
"ad_title": "Selbst der Feuergigant staunt über diese Heißluftfritteuse!",
"brand_name": "EC JEWELRY TRADING CO., LIMITED",
"adv_biz_ids": "7650399223921442817",
"tt_user": null,
"comment": null,
"cost": null,
"country_code": {
"0": "DE"
},
"ctr": null,
"favorite": false,
"has_summary": false,
"highlight_text": "",
"id": "1881677718950002",
"industry_key": null,
"is_search": false,
"keyword_list": null,
"landing_page": "https://tryeloura.eu.cc/products/air-fryer-5-5l?utm_source=tiktok&utm_id=__CAMPAIGN_ID__&utm_campaign=__CAMPAIGN_NAME__&utm_medium=paid",
"estimated_audience": "0-1K",
"location": {
"total_region": 1,
"total_impressions": "0-1K",
"data": {
"0": {
"region": "DE",
"impressions": "0-1K",
"breakdowns": {
"0": {
"age": "13-17",
"gender": "MALE",
"impressions": "0-1K"
},
"1": {
"age": "13-17",
"gender": "FEMALE",
"impressions": "0-1K"
},
"2": {
"age": "13-17",
"gender": "UNKNOWN",
"impressions": "0-1K"
},
"3": {
"age": "18-24",
"gender": "MALE",
"impressions": "0-1K"
},
"4": {
"age": "18-24",
"gender": "FEMALE",
"impressions": "0-1K"
},
"5": {
"age": "18-24",
"gender": "UNKNOWN",
"impressions": "0-1K"
},
"6": {
"age": "25-34",
"gender": "MALE",
"impressions": "0-1K"
},
"7": {
"age": "25-34",
"gender": "FEMALE",
"impressions": "0-1K"
},
"8": {
"age": "25-34",
"gender": "UNKNOWN",
"impressions": "0-1K"
},
"9": {
"age": "35-44",
"gender": "MALE",
"impressions": "0-1K"
},
"10": {
"age": "35-44",
"gender": "FEMALE",
"impressions": "0-1K"
},
"11": {
"age": "35-44",
"gender": "UNKNOWN",
"impressions": "0-1K"
},
"12": {
"age": "45-54",
"gender": "MALE",
"impressions": "0-1K"
},
"13": {
"age": "45-54",
"gender": "FEMALE",
"impressions": "0-1K"
},
"14": {
"age": "45-54",
"gender": "UNKNOWN",
"impressions": "0-1K"
},
"15": {
"age": "55+",
"gender": "MALE",
"impressions": "0-1K"
},
"16": {
"age": "55+",
"gender": "FEMALE",
"impressions": "0-1K"
},
"17": {
"age": "55+",
"gender": "UNKNOWN",
"impressions": "0-1K"
}
}
}
}
},
"like": null,
"objective_key": "Sales",
"objectives": {
"0": {
"label": "Sales",
"value": null
}
},
"pattern_label": {},
"share": null,
"source": "TikTok Ads Library",
"source_key": null,
"video_info": {
"vid": null,
"duration": null,
"cover": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o4Kb26EvNEmOWrgxGyVy6zAIDfAeFDBv3C0VfQ~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=fa083994&x-expires=1794960000&x-signature=%2BTL7AFpNJVwcnCEyaiClPjzA9IQ%3D&t=4d5b0474&ps=13740610&shp=0c75dd76&shcp=9b759fb9&idc=sg1",
"video_url": {
"720p": "https://library.tiktok.com/api/v1/cdn/1794941926/video/aHR0cHM6Ly92MTZtLnRpa3Rva2Nkbi5jb20vMzY3ODI4ZjJkMmM3ZjBmOThjZTYyMTg0OGQ5OTFmYTAvNmFmY2Y4NTUvdmlkZW8vdG9zL2FsaXNnL3Rvcy1hbGlzZy12ZS0wMDUxYzAwMS1zZy9vQUJ2N3ZCeklaaVRBNzFBR1gxOVk5aVVCY1FZM1hPQTNFYUpsLw==/26e31dff-edcd-4ca7-b2b3-dc4e2b317bac?a=475769&bt=744&btag=e000b8000&bti=PDU2NmYwMy86&ft=.NpOcInz7ThtrjxGXq8Zmo&l=2026111802584641B1253AD4E2C55CD894&mime_type=video_mp4&rc=PGg2OmU1Ojo3ZThoNTo6N0BpMzVqOnM5cmh5ZTMzODYzNEA2XmAzLTYwNmMxYl5gMzQuYSMtcC1kMmQ0Ym5hLS1kMDFzcw%3D%3D&signature=k0RhRWTTZ%2FjVL%2BVmjchX%2BMPwFj7fyo0wEechWmW48lE%3D&vvpl=1"
},
"width": null,
"height": null
},
"voice_over": null,
"creative_center_url": null,
"detail_analysis": null,
"interactive_time_analysis": {},
"recommended_for_you": {},
"audit_status": "1",
"sor_audit_status": "1",
"rejection_info": null,
"is_unavailable": false,
"first_shown_date": 1794441600000,
"last_shown_date": 1794528000000,
"image_urls": {
"0": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o4Kb26EvNEmOWrgxGyVy6zAIDfAeFDBv3C0VfQ~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=fa083994&x-expires=1794960000&x-signature=%2BTL7AFpNJVwcnCEyaiClPjzA9IQ%3D&t=4d5b0474&ps=13740610&shp=0c75dd76&shcp=9b759fb9&idc=sg1"
},
"type": "2"
},
"credits_used": 1
}{
"success": false,
"error": "ad_id parameter is required"
}{
"success": false,
"error": "User not authenticated"
}{
"success": false,
"error": "Insufficient credits",
"required": 1,
"available": 0
}💳 1 credit per request
Authorizations
API key for authentication. Format: sk_live_xxxxxxxxxxxxx
Get your API key from the Dashboard.
Query Parameters
Response
Successful response containing ad details
Key Response Fields:
id: Unique ad IDad_title: Ad creative text/captionbrand_name: Brand name (if available)like: Total likescomment: Total commentsshare: Total sharesctr: Click-through ratecountry_code: Countries where the ad ranindustry_key: Industry category identifierobjective_key: Primary campaign objectiveobjectives[]: All objectives with label and weightlanding_page: Ad destination URLsource: Ad source typevideo_info.duration: Video length in secondsvideo_info.cover: Video cover/thumbnail URLvideo_info.video_url: Download URLs by quality (540p, 720p)video_info.width: Video width in pixelsvideo_info.height: Video height in pixelscreative_center_url: Link to the ad on TikTok Creative Centerinteractive_time_analysis: Second-by-second metrics for CTR, CVR, clicks, conversions, and retentionrecommended_for_you: Related ads suggested by Creative Center