TikTok Ads Library Scraper

sfoln/tiktok-ads-search · Social media, Lead generation, Ecommerce On request

Search TikTok's public Ads Library by keyword or advertiser: ad ID, advertiser, first and last shown dates, reach, impressions, video and cover URLs, plus optional caption, countries and landing page. $1.50 per 1,000 ads + $0.004 per results page; ad details $5 per 1,000.

Request access Run it$1.5 / 1,000 tiktok ad, more below

About

What it does

TikTok Ads Library Scraper searches TikTok's public Ads Library by keyword or advertiser name and returns one dataset record per ad: ad ID and library link, advertiser name and business ID, first and last shown dates, estimated reach bucket, impressions and spend when disclosed, video and cover image URLs. Turn on ad details to add the caption, countries, landing page, likes, CTR, campaign objective and best-quality video for every ad. Built for competitor monitoring, creative research, agencies and AI agents.

Price

Price per delivered record

Event	Price	Per 1,000	Charged for
TikTok ad `tiktok-ad`	$0.0015	$1.5 / 1,000	Charged once per ad record delivered from the TikTok Ads Library (recordType ad). Duplicates, ads removed by the date filter, query summary rows and failed requests are not charged.
TikTok Ads Library page `tiktok-ads-query`	$0.004	$4 / 1,000	Charged once per Ads Library results page fetched for a query. A page without new ads is charged only when the upstream provider billed it. Failed requests are not charged.
TikTok ad details `tiktok-ad-details`	$0.005	$5 / 1,000	Optional (includeAdDetails). Charged once per ad enriched with details: caption, countries, landing page, likes, CTR, objective. Not charged when the details request fails.

Apify free plan: up to 10 items per run. Paid plans have no per-run cap; set maxTotalChargeUsd to cap spend.

Run

Call it from code, an agent or the Console

This API is private on Apify for now. Email us and we will publish it for you, usually within two working days. The calls below work once it is public. contact@sfoln.com

curl · synchronous run, rows in the response

curl -X POST "https://api.apify.com/v2/actors/sfoln~tiktok-ads-search/run-sync-get-dataset-items" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"queries":["protein"],"maxAdsPerQuery":10}'

mcp.json · hosted Apify MCP server

{
  "mcpServers": {
    "apify": {
      "type": "http",
      "url": "https://mcp.apify.com?tools=sfoln/tiktok-ads-search"
    }
  }
}

asynchronous run · for large batches

POST https://api.apify.com/v2/actors/sfoln~tiktok-ads-search/runs?maxTotalChargeUsd=1
GET  https://api.apify.com/v2/actor-runs/{runId}            # until status is SUCCEEDED
GET  https://api.apify.com/v2/datasets/{defaultDatasetId}/items?format=json

Authenticate with an Apify API token. MCP clients can instead sign in with OAuth when prompted. Example prompt for an agent: Find 20 recent TikTok ads that mention "protein" and list their advertisers, first and last shown dates and estimated reach.

Input

Input fields

Search TikTok's public Ads Library by keyword or advertiser name. Each query returns one dataset record per ad plus one summary record.

Field	Type	Default	Meaning
`queries`	`array`	—	Search keywords General Ads Library searches, one per line. Accounts on the Apify free plan can process up to 10 queries per run (searches and advertiser names together).
`advertiserNames`	`array`	—	Advertiser names Advertiser names (e.g. Gymshark). The name is resolved to TikTok's advertiser entity, falling back to a name search.
`maxAdsPerQuery`	`integer`	`50`	Max ads per query Maximum ads returned per keyword or advertiser (1–500). Range 1–500.
`shownAfter`	`string`	—	Last shown on or after (YYYY-MM-DD) Optional: keep only ads last shown on or after this date. Results are newest-first, so pagination stops at the first page with only older ads. Filtered ads are not charged.
`includeAdDetails`	`boolean`	`false`	Include ad details Fetch details for every delivered ad (caption, countries, landing page, likes, CTR, objective, best-quality video). Adds one tiktok-ad-details event per ad.
`maxQueries`	`integer`	`100`	Max queries Safety cap on keywords + advertisers processed in this run. Range 1–1000.
`concurrency`	`integer`	`4`	Concurrency Queries processed in parallel (1–8). Range 1–8.
`itemTimeoutSecs`	`integer`	`900`	Time limit per query (seconds) Pagination (and ad-detail calls) for one keyword or advertiser stops cleanly shortly before this limit (60–3600). Raise it for very large per-query limits. Range 60–3600.
`includeRaw`	`boolean`	`false`	Include raw upstream response Attach the unmodified upstream ad object(s) to each ad record under `raw` (larger output).

Example input

{
  "queries": [
    "protein"
  ],
  "maxAdsPerQuery": 10
}

Output

One record per input item

Records land in the run's dataset; a synchronous call returns them directly. Each has a status (ok is charged; everything else is free) and a charged flag. The run's OUTPUT record totals items and charges.

Field	Type	Meaning
`input`	`string \| object`	Input The input query this record belongs to.
`recordType`	`string`	Row type ad (one per ad, charged tiktok-ad) \| query (one summary per query, free).
`status`	`string`	Status ok \| not_found \| error \| skipped_invalid \| skipped_budget \| skipped_free_plan
`charged`	`boolean`	Charged Whether this record incurred a pay-per-event charge.
`chargedEvent`	`string`	Charged event Pay-per-event event charged for this record.
`source`	`string`	Source Upstream data source (scrapecreators = ScrapeCreators API over the public ad library).
`fetchedAt`	`string`	Fetched at ISO timestamp.
`error`	`object`	Error code / message when status is not ok.
`warnings`	`array`	Warnings Non-fatal notes (e.g. stopped early).
`query`	`string \| null`	Query Keyword or advertiser name the row belongs to.
`queryType`	`string \| null`	Query type keyword \| advertiser.
`position`	`integer \| null`	Position 1-based position within the query results (newest shown first).
`adId`	`string \| null`	Ad ID TikTok Ads Library ad ID.
`adLibraryUrl`	`string \| null`	Ad Library URL Public TikTok Ads Library detail page.
`advertiserName`	`string \| null`	Advertiser Advertiser (legal entity) name.
`advertiserId`	`string \| null`	Advertiser ID TikTok advertiser business ID (adv_biz_ids).
`firstShown`	`string \| null`	First shown ISO date the ad was first shown.
`lastShown`	`string \| null`	Last shown ISO date the ad was last shown.
`estimatedAudience`	`string \| null`	Reach (bucket) Estimated unique users reached, e.g. 1K-10K.
`impressions`	`integer \| null`	Impressions Impressions when TikTok discloses them (null otherwise).
`spend`	`string \| null`	Spend Spend text when disclosed.
`videoUrls`	`array`	Video URLs Ad video URLs (best quality first from details when included).
`coverImageUrl`	`string \| null`	Cover image Video cover image.
`imageUrls`	`array`	Image URLs Image creatives.
`detailsFetched`	`boolean \| null`	Details fetched Details were fetched and charged (includeAdDetails).
`detailsChargedEvent`	`string \| null`	Details event tiktok-ad-details when details were charged for this ad.
`caption`	`string \| null`	Caption Ad text / title (details only).
`countries`	`array`	Countries Countries the ad ran in (details only).
`landingPageUrl`	`string \| null`	Landing page Destination URL (details only).
`likes`	`integer \| null`	Likes Likes (details only, mostly Top Ads).
`comments`	`integer \| null`	Comments Comments (details only).
`shares`	`integer \| null`	Shares Shares (details only).
`ctr`	`number \| null`	CTR Click-through rate as reported by Creative Center (details only).
`objective`	`string \| null`	Objective Campaign objective, e.g. reach, conversions (details only).
`industry`	`string \| null`	Industry TikTok industry key (details only).
`videoDurationSecs`	`number \| null`	Video duration (s) Video duration (details only).
`creativeCenterUrl`	`string \| null`	Creative Center URL Creative Center Top Ads link when available (details only).
`resolvedAdvertiserName`	`string \| null`	Resolved advertiser Advertiser entity TikTok matched for an advertiser query (summary rows).
`adsDelivered`	`integer \| null`	Ads delivered Ads delivered for this query (summary rows).
`pagesFetched`	`integer \| null`	Pages fetched Upstream pages fetched (summary rows).
`queryFeesCharged`	`integer \| null`	Page fees charged tiktok-ads-query events charged (summary rows).
`adDetailsCharged`	`integer \| null`	Details charged tiktok-ad-details events charged (summary rows).
`totalResults`	`integer \| null`	Total results Total matching ads reported by TikTok (summary rows).
`stopReason`	`string \| null`	Stop reason limit \| end \| budget \| max_pages \| older_than_filter \| deadline \| error \| empty_pages (summary rows).

Example record

{
  "input": {
    "kind": "advertiser",
    "value": "Gymshark"
  },
  "recordType": "ad",
  "query": "Gymshark",
  "queryType": "advertiser",
  "position": 1,
  "adId": "1871655924410641",
  "adLibraryUrl": "https://library.tiktok.com/ads/detail/?ad_id=1871655924410641",
  "advertiserName": "GYMSHARK LTD",
  "advertiserId": "7078923208527618049",
  "firstShown": "2026-07-25T00:00:00.000Z",
  "lastShown": "2026-07-26T00:00:00.000Z",
  "estimatedAudience": "1K-10K",
  "impressions": null,
  "spend": null,
  "videoUrls": [
    "https://library.tiktok.com/api/v1/cdn/…"
  ],
  "coverImageUrl": "https://p16-common-sign.tiktokcdn.com/…",
  "imageUrls": [],
  "detailsFetched": false,
  "caption": null,
  "countries": [],
  "landingPageUrl": null,
  "status": "ok",
  "charged": true,
  "chargedEvent": "tiktok-ad",
  "source": "scrapecreators",
  "fetchedAt": "2026-10-14T10:00:00.000Z"
}

Machine-readable

This page for agents

/actors/tiktok-ads-search.json — this API as JSON
/actors/tiktok-ads-search.md — this API as Markdown
/catalog.json — the whole catalogue