# TikTok Ads Library Scraper (`sfoln/tiktok-ads-search`)

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.

- Family: Ad intelligence
- Categories: Social media, Lead generation, Ecommerce
- Availability: on request (private on Apify). Email contact@sfoln.com with subject "Access request: TikTok Ads Library Scraper (sfoln/tiktok-ads-search)" before calling; calls fail until it is public.
- JSON: https://www.sfoln.com/actors/tiktok-ads-search.json
- MCP: https://mcp.apify.com?tools=sfoln/tiktok-ads-search
- REST (sync): POST https://api.apify.com/v2/actors/sfoln~tiktok-ads-search/run-sync-get-dataset-items
- REST (async): POST https://api.apify.com/v2/actors/sfoln~tiktok-ads-search/runs

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 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. |

Pay-per-event, USD, billed by Apify; no platform usage charge. Only records with status `ok` are charged. Cap a run with `maxTotalChargeUsd`. Apify free plan: up to 10 per run.

## Run

```bash
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 client configuration:

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

Example prompt: Find 20 recent TikTok ads that mention "protein" and list their advertisers, first and last shown dates and estimated reach.

## Input

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). |
| `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. |
| `concurrency` | integer | `4` | Concurrency: Queries processed in parallel (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. |
| `includeRaw` | boolean | `false` | Include raw upstream response: Attach the unmodified upstream ad object(s) to each ad record under `raw` (larger output). |

Example input:

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

## Output

One record per input item with `status` (`ok` is charged; `not_found`, `error`, `skipped_*` are free) and `charged`. The run stores an `OUTPUT` summary record.

| 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:

```json
{
  "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"
}
```

## Related

- [Ad Library Scraper – Meta, Google & TikTok](https://www.sfoln.com/actors/ad-library-scraper.md) (`sfoln/ad-library-scraper`)
- [Facebook Ads Library Scraper](https://www.sfoln.com/actors/facebook-ads-search.md) (`sfoln/facebook-ads-search`)
- [Google Ads Transparency Scraper](https://www.sfoln.com/actors/google-ads-transparency.md) (`sfoln/google-ads-transparency`)
- [LinkedIn Ads Library Scraper](https://www.sfoln.com/actors/linkedin-ads-search.md) (`sfoln/linkedin-ads-search`)
- [Facebook Ad Details Scraper (by Ad ID)](https://www.sfoln.com/actors/facebook-ad-lookup.md) (`sfoln/facebook-ad-lookup`)

Publisher: SFOLN LLC, contact@sfoln.com. Catalogue: https://www.sfoln.com/catalog.json. Agent guide: https://www.sfoln.com/agents.md.