Get an API key; the examples use
api.socialscrape.dev.Before you start
- An API key, sent in the
x-api-keyheader. Keep it on your server. - For this endpoint you send one of
queryoradvertiser_name. The TikTok Ad Library search page lists every parameter.
Step 1: Send the request
GET /v1/tiktok/ad-library/search. Pick your language; each one reads the key from SOCIALSCRAPE_API_KEY.
1curl -G "https://api.socialscrape.dev/v1/tiktok/ad-library/search" \2 -H "x-api-key: $SOCIALSCRAPE_API_KEY" \3 --data-urlencode 'query="free trial"' \4 --data-urlencode 'start_date=2026-10-22' \5 --data-urlencode 'end_date=2026-10-29'1import os2import requests34params = {5 "query": "\"free trial\"",6 "start_date": "2026-10-22",7 "end_date": "2026-10-29",8}9res = requests.get(10 "https://api.socialscrape.dev/v1/tiktok/ad-library/search",11 headers={"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]},12 params=params,13 timeout=60,14)15body = res.json()1617if body["ok"]:18 print(body["data"])19else:20 print(body["error"]["code"], body["error"]["message"])1const url = new URL("https://api.socialscrape.dev/v1/tiktok/ad-library/search");2url.search = new URLSearchParams({3 query: "\"free trial\"",4 start_date: "2026-10-22",5 end_date: "2026-10-29",6}).toString();7const res = await fetch(url, {8 headers: { "x-api-key": process.env.SOCIALSCRAPE_API_KEY },9});10const body = await res.json();1112if (body.ok) {13 console.log(body.data);14} else {15 console.error(body.error.code, body.error.message);16}1const url = new URL("https://api.socialscrape.dev/v1/tiktok/ad-library/search");2url.search = new URLSearchParams({3 query: "\"free trial\"",4 start_date: "2026-10-22",5 end_date: "2026-10-29",6}).toString();7const res = await fetch(url, {8 headers: { "x-api-key": process.env.SOCIALSCRAPE_API_KEY! },9});10const body = await res.json();1112if (body.ok) {13 console.log(body.data);14} else {15 console.error(body.error.code, body.error.message);16}1package main23import (4 "fmt"5 "io"6 "net/http"7 "net/url"8 "os"9)1011func main() {12 q := url.Values{}13 q.Set("query", "\"free trial\"")14 q.Set("start_date", "2026-10-22")15 q.Set("end_date", "2026-10-29")16 req, _ := http.NewRequest("GET", "https://api.socialscrape.dev/v1/tiktok/ad-library/search" + "?" + q.Encode(), nil)17 req.Header.Set("x-api-key", os.Getenv("SOCIALSCRAPE_API_KEY"))18 res, err := http.DefaultClient.Do(req)19 if err != nil {20 panic(err)21 }22 defer res.Body.Close()23 body, _ := io.ReadAll(res.Body)24 fmt.Println(res.StatusCode, string(body))25}1<?php2$query = http_build_query([3 'query' => '"free trial"',4 'start_date' => '2026-10-22',5 'end_date' => '2026-10-29',6]);7$ch = curl_init('https://api.socialscrape.dev/v1/tiktok/ad-library/search' . "?" . $query);8curl_setopt_array($ch, [9 CURLOPT_RETURNTRANSFER => true,10 CURLOPT_HTTPHEADER => ["x-api-key: " . getenv("SOCIALSCRAPE_API_KEY")],11]);12$body = json_decode(curl_exec($ch), true);13curl_close($ch);1415if ($body["ok"]) {16 print_r($body["data"]);17} else {18 echo $body["error"]["code"], " ", $body["error"]["message"], "\n";19}1require "net/http"2require "json"34uri = URI('https://api.socialscrape.dev/v1/tiktok/ad-library/search')5uri.query = URI.encode_www_form('query' => '"free trial"', 'start_date' => '2026-10-22', 'end_date' => '2026-10-29')6req = Net::HTTP::Get.new(uri)7req["x-api-key"] = ENV.fetch("SOCIALSCRAPE_API_KEY")8res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }9body = JSON.parse(res.body)1011if body["ok"]12 puts body["data"]13else14 puts body["error"]["code"], body["error"]["message"]15end1import java.net.URI;2import java.net.URLEncoder;3import java.net.http.HttpClient;4import java.net.http.HttpRequest;5import java.net.http.HttpResponse;6import java.nio.charset.StandardCharsets;78public class Main {9 public static void main(String[] args) throws Exception {10 String query = "query=" + URLEncoder.encode("\"free trial\"", StandardCharsets.UTF_8) + "&start_date=" + URLEncoder.encode("2026-10-22", StandardCharsets.UTF_8) + "&end_date=" + URLEncoder.encode("2026-10-29", StandardCharsets.UTF_8);11 HttpRequest req = HttpRequest.newBuilder()12 .uri(URI.create("https://api.socialscrape.dev/v1/tiktok/ad-library/search" + "?" + query))13 .header("x-api-key", System.getenv("SOCIALSCRAPE_API_KEY"))14 .GET()15 .build();16 HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());17 System.out.println(res.statusCode() + " " + res.body());18 }19}1using System;2using System.Net.Http;34var client = new HttpClient();5client.DefaultRequestHeaders.Add("x-api-key", Environment.GetEnvironmentVariable("SOCIALSCRAPE_API_KEY"));6var query = string.Join("&", new[] {7 "query=" + Uri.EscapeDataString("\"free trial\""),8 "start_date=" + Uri.EscapeDataString("2026-10-22"),9 "end_date=" + Uri.EscapeDataString("2026-10-29"),10});11var res = await client.GetAsync("https://api.socialscrape.dev/v1/tiktok/ad-library/search" + "?" + query);12Console.WriteLine((int)res.StatusCode);13Console.WriteLine(await res.Content.ReadAsStringAsync());Step 2: Read the response
Results are in data.items. Here is what one item gives you, from a recorded sample.
1for item in body["data"]["items"]:2 print(item["title"])3 print(item["id"])1for (const item of body.data.items) {2 console.log(item.title);3 console.log(item.id);4}SampleFields printed above
1{2 "title": "This year, sleep deeper, train smarter, and live better for longer. Start your WHOOP free trial.",3 "id": "1880321679899026"4}A field the platform does not give comes back as null. The full field list is on the endpoint page.
Step 3: Get the next page
Send the same request with the cursor you got back, until has_more is false. Each page costs its own price.
1import os2import requests34url = "https://api.socialscrape.dev/v1/tiktok/ad-library/search"5headers = {"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]}6params = {"query": "\"free trial\"", "start_date": "2026-10-22", "end_date": "2026-10-29"}78items = []9while len(items) < 100:10 body = requests.get(url, headers=headers, params=params, timeout=60).json()11 if not body["ok"]:12 raise RuntimeError(body["error"]["code"])13 items += body["data"]["items"]14 if not body["has_more"]:15 break16 params["cursor"] = body["cursor"]1718print(len(items), "items")1const url = new URL("https://api.socialscrape.dev/v1/tiktok/ad-library/search");2url.searchParams.set("query", "\"free trial\"");3url.searchParams.set("start_date", "2026-10-22");4url.searchParams.set("end_date", "2026-10-29");5const headers = { "x-api-key": process.env.SOCIALSCRAPE_API_KEY };67const items = [];8while (items.length < 100) {9 const body = await (await fetch(url, { headers })).json();10 if (!body.ok) throw new Error(body.error.code);11 items.push(...body.data.items);12 if (!body.has_more) break;13 url.searchParams.set("cursor", body.cursor);14}1516console.log(items.length, "items");Step 4: Handle errors
Check ok, then branch on error.code and error.retryable, never on the message.
1body = res.json()2if not body["ok"]:3 err = body["error"]4 if err["retryable"]:5 ... # wait a moment and send the same request again6 else:7 raise RuntimeError(f'{err["code"]}: {err["message"]}')1const body = await res.json();2if (!body.ok) {3 const { code, message, retryable } = body.error;4 if (retryable) {5 // wait a moment and send the same request again6 } else {7 throw new Error(`${code}: ${message}`);8 }9}| Code | HTTP | Retry | Meaning |
|---|---|---|---|
invalid_params | 400 | no | A parameter is missing, unknown or has the wrong type. |
not_found | 404 | no | The platform says this profile, post or item does not exist. |
upstream_blocked | 503 | yes | The platform blocked this fetch; retry (a fresh exit is used). |
Other errors, such as unauthorized or rate_limited, are on the errors page.
With the SDK
The Python and TypeScript clients wrap all of this: typed errors, retries, and cursor paging. Install them with pip install socialscrape-sdk or npm install socialscrape.
1from socialscrape import SocialScrape23client = SocialScrape() # reads SOCIALSCRAPE_API_KEY45for item in client.paginate(client.tiktok.ad_library_search, query="\"free trial\"", start_date="2026-10-22", end_date="2026-10-29", max_items=100):6 print(item["title"])1import { SocialScrape } from "socialscrape";23const client = new SocialScrape(); // reads SOCIALSCRAPE_API_KEY45for await (const item of client.paginate(client.tiktok.adLibrarySearch, { query: "\"free trial\"", start_date: "2026-10-22", end_date: "2026-10-29" }, { maxItems: 100 })) {6 console.log(item.title);7}What it costs
1 credit. A failed request costs nothing. Add max_age_days to reuse a cached result for 0 credits. Results are kept 30 days.
Next
- TikTok Ad Library search API: sample response and every parameter.
- A full Python script and a full JavaScript script for this endpoint.
- All TikTok endpoints.