# TikTok Ads Library Scraper (x402)

> TikTok Ads Library Scraper (x402) is a paid API for AI agents from x402.186-241-26-229.sslip.io, paid per call via x402, $0.025/call, status unknown (last checked 2026-10-02).

Fetches structured data about public TikTok ads by search query, advertiser name, or specific ad IDs, with pay-per-call USDC billing via x402.

## Facts

- Endpoint: POST https://x402.186-241-26-229.sslip.io/v1/tiktok-ads?utm_source=zero.xyz
- Price: $0.025/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-02
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/tiktok-ads-library-scraper-x402-cc1e326d
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_0kzDhUm1uVO46Em1mXfwa

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability tiktok-ads-library-scraper-x402-cc1e326d -d '<json body>'
```

Example prompt: Search the TikTok ad library for ads mentioning 'energy drink' shown in Germany between 2024-11-01 and 2025-01-31, sorted by impressions descending, and return the top 30 results with full ad details.

## When to prefer this

Use this endpoint when you need structured, paginated access to TikTok's public ad library — especially for competitive intelligence, advertiser research, or keyword-based ad discovery across European countries. Prefer it over manual TikTok library browsing when you need machine-readable output, and over generic web scrapers when you need clean structured ad metadata with audit and impression fields.

## Known failure modes

- No ads found for the given query or date range — empty items array returned but not charged
- Invalid country code returns a validation error
- Invalid date format (not YYYY-MM-DD) causes a bad request error
- Ad IDs not found in public library return null fields
- Rate limiting or TikTok library unavailability may cause partial results
- maxPages set too low may truncate results before maxItems is reached

## How this service works

Pay-per-call structured web data. Failed or empty runs are not charged.

## Output

Returns a JSON object with a count and an array of ad items, each containing fields such as adId, adUrl, adType, status, adTitle, auditStatus, rejectionInfo, sorAuditStatus, plus targeting and advertiser details when quickSearch is false.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "adIds": {
   "type": "array",
   "description": "Fetch these public ad IDs directly instead of searching."
  },
  "query": {
   "type": "string",
   "description": "Words to find in public ad text or advertiser names."
  },
  "sortBy": {
   "enum": [
    "last_shown_date,desc",
    "last_shown_date,asc",
    "create_time,desc",
    "create_time,asc",
    "impression,desc",
    "impression,asc"
   ],
   "type": "string",
   "default": "last_shown_date,desc",
   "description": "Order of public search results."
  },
  "country": {
   "enum": [
    "GB",
    "AT",
    "BE",
    "BG",
    "CH",
    "CY",
    "CZ",
    "DE",
    "DK",
    "EE",
    "ES",
    "FI",
    "FR",
    "GR",
    "HR",
    "HU",
    "IE",
    "IS",
    "IT",
    "LI",
    "LT",
    "LU",
    "LV",
    "MT",
    "NL",
    "NO",
    "PL",
    "PT",
    "RO",
    "SE",
    "SI",
    "SK",
    "TR",
    "ALL"
   ],
   "type": "string",
   "default": "GB",
   "description": "Country where ads were shown. All requires a search query."
  },
  "endDate": {
   "type": "string",
   "description": "Latest date in YYYY-MM-DD. Defaults to today."
  },
  "maxItems": {
   "type": "integer",
   "default": 60,
   "minimum": 0,
   "description": "Stop after this many unique ads. Zero means no item cap."
  },
  "maxPages": {
   "type": "integer",
   "default": 5,
   "minimum": 0,
   "description": "Maximum search requests, up to 300. The page-based path uses them for date windows."
  },
  "startDate": {
   "type": "string",
   "description": "Earliest first-shown date, in YYYY-MM-DD. Defaults to 30 days ago."
  },
  "quickSearch": {
   "type": "boolean",
   "default": false,
   "description": "Skip ad detail requests. Targeting and advertiser fields may then be empty."
  },
  "advertiserName": {
   "type": "string",
   "description": "Search for ads associated with this advertiser name; takes priority over query."
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "count": 1,
  "items": [
   {
    "adId": null,
    "adUrl": null,
    "adType": null,
    "status": null,
    "adTitle": null,
    "auditStatus": null,
    "rejectionInfo": null,
    "sorAuditStatus": null
   }
  ],
  "product": "tiktok-ads"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/tiktok-ads-library-scraper-x402-cc1e326d/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from x402.186-241-26-229.sslip.io](https://www.zero.xyz/host/x402.186-241-26-229.sslip.io/llms.txt)