TikTok — top ads

curl --request POST \
  --url https://app.sideshift.app/api/v1/scrape/tiktok/ads \
  --header 'Content-Type: application/json' \
  --data '
{
  "country_code": "US",
  "period": 7
}
'

import requests

url = "https://app.sideshift.app/api/v1/scrape/tiktok/ads"

payload = {
    "country_code": "US",
    "period": 7
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({country_code: 'US', period: 7})
};

fetch('https://app.sideshift.app/api/v1/scrape/tiktok/ads', 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://app.sideshift.app/api/v1/scrape/tiktok/ads",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'country_code' => 'US',
    'period' => 7
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.sideshift.app/api/v1/scrape/tiktok/ads"

	payload := strings.NewReader("{\n  \"country_code\": \"US\",\n  \"period\": 7\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.sideshift.app/api/v1/scrape/tiktok/ads")
  .header("Content-Type", "application/json")
  .body("{\n  \"country_code\": \"US\",\n  \"period\": 7\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.sideshift.app/api/v1/scrape/tiktok/ads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"country_code\": \"US\",\n  \"period\": 7\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "cursor": "2",
    "has_more": true,
    "page": 1,
    "page_size": 20,
    "total": 22,
    "ads": [
      {
        "title": "Australia, Cozey is here with thoughtfully designed furniture and fast, free shipping from Sydney.",
        "like_count": 288,
        "video": {
          "cover_url": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/ooZR8AfOUbQL4jNjDPgMIsFEN85IHqZJDfBMB1~tplv-noop.image",
          "video_id": "v14033g50000d9mccjvog65u49opc4e0",
          "video_link": "https://v16m-default.tiktokcdn.com/ea13104f90cbac2fc5775536289ba22b/6a77e3ba/video/tos/alisg/tos-alisg-ve-0051c001-sg/owbAcBEMnRDNNGgEZILWFXsBfeUQVqEDxGIPnv/",
          "duration_seconds": 28.067,
          "height": 1280,
          "width": 720,
          "video_links_by_quality": {
            "1080p": "https://v16m-default.tiktokcdn.com/ea13104f90cbac2fc5775536289ba22b/6a77e3ba/video/tos/alisg/tos-alisg-ve-0051c001-sg/owbAcBEMnRDNNGgEZILWFXsBfeUQVqEDxGIPnv/",
            "360p": "https://v16m-default.tiktokcdn.com/e1f7d9495537303de4c76802e8675c8d/6a77e3ba/video/tos/alisg/tos-alisg-ve-0051c001-sg/o4dgnExPAIZDMeUqNXcBBWGpmEEKIQFsPBCbfD/",
            "480p": "https://v16m-default.tiktokcdn.com/2cdff4844d0c3411cae90329196c6e74/6a77e3ba/video/tos/alisg/tos-alisg-ve-0051c001-sg/oQUD4GD7EDrgIMFgqfIAMjMfRZ8NBPDbZQBmOs/",
            "540p": "https://v16m-default.tiktokcdn.com/7b61fb925f321ddf796f208b50e72c46/6a77e3ba/video/tos/alisg/tos-alisg-ve-0051c001-sg/oQFZMJOqbA2sBIPgE8OMTNjBUfZfI4MbDR4gQD/",
            "720p": "https://v16m-default.tiktokcdn.com/3ba5537a0909b760e98f610434bb35e4/6a77e3ba/video/tos/alisg/tos-alisg-ve-0051c001-sg/o8IcrNBqWbsxZFWDec9DmgQDUEBfAPI4GEGnEM/"
          }
        },
        "ad_id": "7668717763499327508",
        "brand_name": "cozey",
        "industry_key": "label_21000000000",
        "objective_key": "campaign_objective_traffic",
        "cost_level": 2,
        "ctr": 0.25,
        "is_search_ad": true
      }
    ]
  },
  "request_id": "req_8f3c9a2b1d4e6f70",
  "upstream_calls": 1,
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 9998
  }
}

{
  "error": "INVALID_INPUT",
  "message": "Invalid request body.",
  "request_id": "req_8f3c9a2b1d4e6f70"
}

{
  "error": "UNAUTHORIZED",
  "message": "Invalid scraper API key.",
  "request_id": "req_8f3c9a2b1d4e6f70"
}

{
  "error": "INSUFFICIENT_SCRAPER_CREDITS",
  "message": "Insufficient scraper credits.",
  "request_id": "req_8f3c9a2b1d4e6f70"
}

{
  "error": "RESOURCE_NOT_FOUND",
  "message": "Requested resource not found or unavailable.",
  "request_id": "req_8f3c9a2b1d4e6f70"
}

{
  "error": "PAYLOAD_TOO_LARGE",
  "message": "Request body must be 32KB or smaller.",
  "request_id": "req_8f3c9a2b1d4e6f70"
}

{
  "error": "SCRAPER_RATE_LIMITED",
  "message": "Scraper API rate limit exceeded.",
  "request_id": "req_8f3c9a2b1d4e6f70"
}

{
  "error": "INTERNAL_ERROR",
  "message": "Request failed. Your credits were refunded.",
  "request_id": "req_8f3c9a2b1d4e6f70"
}

{
  "error": "UPSTREAM_ERROR",
  "message": "Data source failed. Your credits were refunded.",
  "request_id": "req_8f3c9a2b1d4e6f70"
}

{
  "error": "UPSTREAM_TIMEOUT",
  "message": "Data source timed out. Your credits were refunded.",
  "request_id": "req_8f3c9a2b1d4e6f70"
}

POST

scrape

tiktok

ads

TikTok — top ads

curl --request POST \
  --url https://app.sideshift.app/api/v1/scrape/tiktok/ads \
  --header 'Content-Type: application/json' \
  --data '
{
  "country_code": "US",
  "period": 7
}
'

import requests

url = "https://app.sideshift.app/api/v1/scrape/tiktok/ads"

payload = {
    "country_code": "US",
    "period": 7
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({country_code: 'US', period: 7})
};

fetch('https://app.sideshift.app/api/v1/scrape/tiktok/ads', 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://app.sideshift.app/api/v1/scrape/tiktok/ads",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'country_code' => 'US',
    'period' => 7
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.sideshift.app/api/v1/scrape/tiktok/ads"

	payload := strings.NewReader("{\n  \"country_code\": \"US\",\n  \"period\": 7\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.sideshift.app/api/v1/scrape/tiktok/ads")
  .header("Content-Type", "application/json")
  .body("{\n  \"country_code\": \"US\",\n  \"period\": 7\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.sideshift.app/api/v1/scrape/tiktok/ads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"country_code\": \"US\",\n  \"period\": 7\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "cursor": "2",
    "has_more": true,
    "page": 1,
    "page_size": 20,
    "total": 22,
    "ads": [
      {
        "title": "Australia, Cozey is here with thoughtfully designed furniture and fast, free shipping from Sydney.",
        "like_count": 288,
        "video": {
          "cover_url": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/ooZR8AfOUbQL4jNjDPgMIsFEN85IHqZJDfBMB1~tplv-noop.image",
          "video_id": "v14033g50000d9mccjvog65u49opc4e0",
          "video_link": "https://v16m-default.tiktokcdn.com/ea13104f90cbac2fc5775536289ba22b/6a77e3ba/video/tos/alisg/tos-alisg-ve-0051c001-sg/owbAcBEMnRDNNGgEZILWFXsBfeUQVqEDxGIPnv/",
          "duration_seconds": 28.067,
          "height": 1280,
          "width": 720,
          "video_links_by_quality": {
            "1080p": "https://v16m-default.tiktokcdn.com/ea13104f90cbac2fc5775536289ba22b/6a77e3ba/video/tos/alisg/tos-alisg-ve-0051c001-sg/owbAcBEMnRDNNGgEZILWFXsBfeUQVqEDxGIPnv/",
            "360p": "https://v16m-default.tiktokcdn.com/e1f7d9495537303de4c76802e8675c8d/6a77e3ba/video/tos/alisg/tos-alisg-ve-0051c001-sg/o4dgnExPAIZDMeUqNXcBBWGpmEEKIQFsPBCbfD/",
            "480p": "https://v16m-default.tiktokcdn.com/2cdff4844d0c3411cae90329196c6e74/6a77e3ba/video/tos/alisg/tos-alisg-ve-0051c001-sg/oQUD4GD7EDrgIMFgqfIAMjMfRZ8NBPDbZQBmOs/",
            "540p": "https://v16m-default.tiktokcdn.com/7b61fb925f321ddf796f208b50e72c46/6a77e3ba/video/tos/alisg/tos-alisg-ve-0051c001-sg/oQFZMJOqbA2sBIPgE8OMTNjBUfZfI4MbDR4gQD/",
            "720p": "https://v16m-default.tiktokcdn.com/3ba5537a0909b760e98f610434bb35e4/6a77e3ba/video/tos/alisg/tos-alisg-ve-0051c001-sg/o8IcrNBqWbsxZFWDec9DmgQDUEBfAPI4GEGnEM/"
          }
        },
        "ad_id": "7668717763499327508",
        "brand_name": "cozey",
        "industry_key": "label_21000000000",
        "objective_key": "campaign_objective_traffic",
        "cost_level": 2,
        "ctr": 0.25,
        "is_search_ad": true
      }
    ]
  },
  "request_id": "req_8f3c9a2b1d4e6f70",
  "upstream_calls": 1,
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 9998
  }
}

{
  "error": "INVALID_INPUT",
  "message": "Invalid request body.",
  "request_id": "req_8f3c9a2b1d4e6f70"
}

{
  "error": "UNAUTHORIZED",
  "message": "Invalid scraper API key.",
  "request_id": "req_8f3c9a2b1d4e6f70"
}

{
  "error": "INSUFFICIENT_SCRAPER_CREDITS",
  "message": "Insufficient scraper credits.",
  "request_id": "req_8f3c9a2b1d4e6f70"
}

{
  "error": "RESOURCE_NOT_FOUND",
  "message": "Requested resource not found or unavailable.",
  "request_id": "req_8f3c9a2b1d4e6f70"
}

{
  "error": "PAYLOAD_TOO_LARGE",
  "message": "Request body must be 32KB or smaller.",
  "request_id": "req_8f3c9a2b1d4e6f70"
}

{
  "error": "SCRAPER_RATE_LIMITED",
  "message": "Scraper API rate limit exceeded.",
  "request_id": "req_8f3c9a2b1d4e6f70"
}

{
  "error": "INTERNAL_ERROR",
  "message": "Request failed. Your credits were refunded.",
  "request_id": "req_8f3c9a2b1d4e6f70"
}

{
  "error": "UPSTREAM_ERROR",
  "message": "Data source failed. Your credits were refunded.",
  "request_id": "req_8f3c9a2b1d4e6f70"
}

{
  "error": "UPSTREAM_TIMEOUT",
  "message": "Data source timed out. Your credits were refunded.",
  "request_id": "req_8f3c9a2b1d4e6f70"
}

Body

application/json

page

integer

default:1

One-indexed result page.

Required range: x >= 1

cursor

string | null

Opaque ad-library pagination token.

Maximum string length: 32768

limit

integer

default:20

Ads per page.

Required range: 1 <= x <= 20

period

enum<integer> | null

Look-back window in days.

Available options:

7,

30,

180

country_code

string | null

Comma-separated two-letter markets.

ad_language

string | null

Comma-separated language codes.

order_by

enum<string> | null

Ranking metric.

Available options:

impression,

ctr,

like,

cvr,

play_6s_rate,

play_2s_rate

industry

string | null

Comma-separated industry codes.

ad_format

enum<string> | null

Ad format code.

Available options:

1,

2

objective

string | null

Comma-separated campaign objective codes.

enum<string> | null

Like percentile-band code.

Available options:

1,

2,

3,

4,

5

keyword

string | null

Free-text ad-library keyword.

Response

Completed lookup. Standard cost: 1 SideShift credit; account-specific pricing, when present, is shown in the Scraper dashboard and returned in the billing headers.

data

object

required

TikTok platform data payload. Field names and nesting are preserved.

Show child attributes

request_id

string

required

SideShift request id. Include it in support requests.

upstream_calls

enum<integer>

required

Number of data-source lookups performed.

Available options:

1

Guides

Reference

TikTok — top ads

Body

Response