TikTok Ads Library Scraper

TikTok Ads Library Scraper helps analysts and agents search TikTok's public Ads Library by advertiser, keyword, business ID, country, date range, or a copied filtered library URL. One dataset record represents one public ad and can include creative media, advertiser identity, status, first and last shown dates, public audience estimates, targeting details when requested, and source links. The Actor is usable through Apify and through Apify MCP for structured advertising-transparency workflows.

Best fit and connected workflows

Use this Actor when your workflow starts with public TikTok ad evidence and needs reproducible rows for research, monitoring, or enrichment.

It fits well when you want to:

• review competitor ads in EEA, Swiss, or U.K. public library coverage,
• compare creatives across advertisers or keywords,
• reproduce an existing filtered Ads Library search from a copied URL,
• enrich saved ads with public targeting, sponsor, and regional detail fields,
• combine hashtag or topic discovery with paid-ad research.

For discovery upstream, pair it with TikTok Trending Hashtags Scraper when you want a topic or hashtag signal first, then use the resulting public phrase or identifier here as a search input.

Opening contract

This Actor accepts public Ads Library search input for EEA countries, Switzerland, and the United Kingdom. You can search by advertiser name, keyword, advertiser business ID, or a fully filtered libraryUrl. It returns one validated row per ad, which is useful when you need a single structured record with media URLs, ad status, first and last shown dates, audience estimate, and reproducible source evidence.

When includeDetails is enabled, the output can also include public advertiser, sponsor, targeting, age, gender, interest, and region breakdown fields. The Actor returns public transparency data only.

Practical scenario

Priya, a market analyst, starts with "running shoes" in Germany. The first run returns a small set of public ads with advertiserName, title, auditStatus, creativeType, firstShownAt, lastShownAt, estimatedAudience, and adDetailUrl. She uses those fields to shortlist the most relevant advertisers, then reruns the selected brand names with includeDetails: true to add public targeting context. Her next step is to export the rows into a spreadsheet keyed by adId and compare which creatives remain active over time.

Input fields

Field	Type	Purpose	Example
libraryUrl	string	Replays a fully filtered public https://library.tiktok.com/ads search URL	https://library.tiktok.com/ads?region=DE&adv_name=adidas&query_type=1
country	string enum	Selects the public target country and matching browser session	DE
searchQuery	string	Searches by advertiser name or keyword phrase	adidas
searchType	string enum	Interprets searchQuery as keyword or advertiser	advertiser
advertiserBusinessId	string	Applies an exact advertiser business filter	6885261436319171329
dateFrom	string	Sets the inclusive start of the public-library date range	a source-provided date
dateTo	string	Sets the inclusive end of the public-library date range	a source-provided date
maxResults	integer	Caps validated ads written to the dataset	50
includeDetails	boolean	Adds public ad-detail fields when available	true
requestTimeoutSecs	integer	Sets navigation and public-request timeout	60

Focused JSON input example

{
  "country": "DE",
  "searchQuery": "adidas",
  "searchType": "advertiser",
  "advertiserBusinessId": "6885261436319171329",
  "dateFrom": "2026-01-01",
  "dateTo": "2026-03-31",
  "maxResults": 10,
  "includeDetails": true,
  "requestTimeoutSecs": 60
}

Output fields

One dataset item represents one public TikTok ad record.

Field group	Fields	Meaning
Identity and provenance	adId, adDetailUrl, libraryUrl, source, scrapedAt	Public identifier, source link, and extraction timestamp
Search context	country, searchQuery	The search context used for the row
Advertiser	advertiserName, advertiserBusinessId, advertiserRegistryLocation, sponsor	Public advertiser and paying-entity details when exposed
Creative	title, callToAction, landingPageUrl, creativeType, videoUrls, imageUrls, coverImageUrls	Creative copy and public media/destination links
Lifecycle	auditStatus, adType, firstShownAt, lastShownAt	Public state and visible first/last shown timestamps
Scale	estimatedAudience, spend, impressions	Public audience and volume values or ranges
Targeting	targetCountries, targetAudienceSize, targetAgeRanges, targetGender, targetInterests, audienceByRegion	Public targeting fields when detail enrichment is enabled
Enrichment flag	detailEnriched	true when the public detail endpoint added fields

Illustrative JSON output record

{
  "adId": "1866894275556450",
  "adDetailUrl": "https://library.tiktok.com/ads/detail/?ad_id=1866894275556450",
  "libraryUrl": "https://library.tiktok.com/ads?region=DE&adv_name=adidas",
  "country": "DE",
  "searchQuery": "adidas",
  "advertiserName": "adidas AG",
  "advertiserBusinessId": "6885261436319171329",
  "advertiserRegistryLocation": "United Kingdom",
  "sponsor": "MEDIACOM UK LIMITED",
  "auditStatus": "ACTIVE",
  "adType": "2",
  "title": "Just 5 more minutes!",
  "callToAction": "Watch now",
  "landingPageUrl": "https://example.com/product",
  "advertisingObjective": "Video views",
  "firstShownAt": "2026-06-10T00:00:00.000Z",
  "lastShownAt": "2026-06-26T00:00:00.000Z",
  "estimatedAudience": "1M-10M",
  "spend": null,
  "impressions": 0,
  "creativeType": "VIDEO",
  "videoUrls": [
    "https://library.tiktok.com/api/v1/cdn/.../video/..."
  ],
  "imageUrls": [],
  "coverImageUrls": [
    "https://p16-common-sign.tiktokcdn.com/...jpeg"
  ],
  "targetCountries": [
    "DE"
  ],
  "targetAudienceSize": "6.5M-8.0M",
  "targetAgeRanges": [
    "18-24",
    "25-34"
  ],
  "targetGender": [
    "female",
    "male"
  ],
  "targetInterests": "Sports, Fitness",
  "audienceByRegion": [
    {
      "country": "DE",
      "impressions": "1.9M"
    }
  ],
  "detailEnriched": true,
  "source": "tiktok_ads_library",
  "scrapedAt": "2026-07-14T12:00:00.000Z"
}

How it works

1. The Actor validates the JSON input against the live schema.
2. It either builds a bounded public-library search or reproduces an exact copied libraryUrl.
3. It opens TikTok's public Ads Library in a residential browser session for the selected target country.
4. It paginates through public search results until maxResults is reached or no more ads are returned.
5. When includeDetails is enabled, it requests the public ad-detail route for extra advertiser, targeting, audience, and regional fields.
6. It normalizes identifiers, dates, media URLs, nulls, and public status values before saving rows.
7. Each saved row maps to the primary TikTok ad scraped event, and detail enrichment maps to a separate Ad details enriched event when the public detail response succeeds.
8. It writes dataset items plus OUTPUT and RUN_SUMMARY records for downstream automation and agent workflows.

Pricing and usage

This Actor uses Pay per event plus Apify platform usage.

Billing events in the live contract are:

• apify-actor-start: charged when the Actor starts, one event per allocated GB or part thereof, with a one-event minimum
• ad-scraped: charged for each validated TikTok Ads Library record written to the dataset
• detail-enriched: charged when the public detail endpoint returns additional targeting and advertiser fields

Example in words: if you run a search that saves twenty ads and enriches all twenty with public detail data at one GB of memory, your named events include one start event, twenty ad-scraped events, and twenty detail-enriched events. The live Pricing tab on the Actor page shows the current pricing details.

Use with AI agents (MCP)

This Actor is available through Apify MCP as a tool for structured public TikTok ad research. It searches the exact Actor identity khadinakbar/tiktok-ads-library-scraper and returns dataset rows with provenance, public media links, and optional detail fields.

Tool description: search TikTok's public Ads Library for public ad records and return one structured row per ad, with optional public advertiser and targeting enrichment.

Search TikTok's public Ads Library for Germany using the advertiser phrase "adidas". Set maxResults to 5 and includeDetails to false. After the run, read OUTPUT.outcome, then load the dataset and summarize each row with advertiserName, title, auditStatus, creativeType, firstShownAt, lastShownAt, estimatedAudience, and adDetailUrl. Preserve null values. If detail data is present, mention detailEnriched and any public targeting fields. If the run is VALID_EMPTY, report the filters and the public coverage window. If the run is INVALID_INPUT, surface the exact field that needs correction.

Output interpretation and scope guidance:

• adDetailUrl is the suitable source link for review and citation.
• detailEnriched: true means a public detail response added extra fields.
• targetCountries, targetAgeRanges, targetGender, and audienceByRegion come from public detail data when exposed.
• videoUrls and coverImageUrls are public creative links and may be short-lived.
• maxResults is a whole-run cap and also a cost boundary.
• OUTPUT, then the dataset, then RUN_SUMMARY is the most useful read order for agents.

Run with the Apify API

JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });

const run = await client.actor('khadinakbar/tiktok-ads-library-scraper').call({
  country: 'DE',
  searchQuery: 'adidas',
  searchType: 'advertiser',
  maxResults: 5,
  includeDetails: false,
  requestTimeoutSecs: 60,
});

const datasetItems = await client.dataset(run.defaultDatasetId).listItems();
const output = await client.keyValueStore(run.defaultKeyValueStoreId).getRecord('OUTPUT');

console.log('Outcome:', output?.value?.outcome);
console.log('Rows:', datasetItems.items.length);
console.log(datasetItems.items);

Python

import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])

run = client.actor("khadinakbar/tiktok-ads-library-scraper").call(run_input={
    "country": "DE",
    "searchQuery": "adidas",
    "searchType": "advertiser",
    "maxResults": 5,
    "includeDetails": False,
    "requestTimeoutSecs": 60,
})

items = list(client.dataset(run["defaultDatasetId"]).iterate_items())
output = client.key_value_store(run["defaultKeyValueStoreId"]).get_record("OUTPUT")

print("Outcome:", output["value"]["outcome"])
print("Rows:", len(items))
print(items)

Best results and outcome guidance

Start with a narrow query and a small maxResults value, then widen the search only after the first dataset rows look relevant. Use searchType: "keyword" for phrases found in creatives and searchType: "advertiser" for brand or entity names. Keep libraryUrl for exact reproduction of a filtered Ads Library search, and use advertiserBusinessId when you need a precise public advertiser filter.

For detail-heavy workflows, turn on includeDetails only when you need public targeting, sponsor, audience-size, or regional fields. For a basic creative review, the default public search fields are often enough. Compare rows by adId and retain adDetailUrl as your citation path.

Design note

I found that the output contract always includes videoUrls, imageUrls, coverImageUrls, targetCountries, targetAgeRanges, targetGender, audienceByRegion, detailEnriched, source, and scrapedAt in every dataset record, which makes the row shape stable for downstream parsing.

Related Actors

• Use TikTok Trending Hashtags Scraper - upstream discovery for topics or hashtags that can become deliberate keyword searches here.

FAQ

When should I use libraryUrl instead of individual fields?

Use libraryUrl when you already have a filtered public Ads Library URL and want to reproduce that exact search. It overrides the other search fields.

When should I use advertiserBusinessId?

Use advertiserBusinessId when you know TikTok's public advertiser business ID and want an exact advertiser filter in addition to or instead of a name phrase.

What does includeDetails add?

It requests public advertiser-detail data such as sponsor, target countries, target audience size, age ranges, gender, interests, and region summaries when TikTok exposes them.

How should I interpret estimatedAudience and impressions?

They are public transparency fields or ranges from TikTok's Ads Library. They are useful for comparison within the same method and query context.

Can I use this Actor for organic TikTok posts or profiles?

This Actor is built for public paid-ad research in the Ads Library. For organic discovery workflows, start with a TikTok search or trending-content Actor, then move a relevant phrase into this Actor.

What is the practical difference between country and my company location?

country selects the public Ads Library target country where TikTok exposes the ad record. It is the ad market you want to inspect, not your own company location.

Responsible use

Use this Actor for public advertising-transparency research, compliance review, and permitted analysis of public records. Respect applicable law, TikTok terms, privacy obligations, intellectual-property rights, and retention rules. Keep access restricted, retain source URLs and collection timestamps where appropriate, and apply proportionate deletion controls.

Public ad records are transparency data, not private campaign truth. When a field is missing, treat it as an unexposed public value rather than forcing a guess.