{"uid":"cap_0kzDhUm1uVO46Em1mXfwa","slug":"tiktok-ads-library-scraper-x402-cc1e326d","name":"TikTok Ads Library Scraper (x402)","description":"Pay-per-call structured web data. Failed or empty runs are not charged.","url":"https://x402.186-241-26-229.sslip.io/v1/tiktok-ads?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"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."}}},"responseSchema":{"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"}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.025","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.025/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.025","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.025","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_Z_xB_qsww4o1XsDBGwrMx","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.025","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Fetches structured data about public TikTok ads by search query, advertiser name, or specific ad IDs, with pay-per-call USDC billing via x402.","exampleAgentPrompt":"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.","exampleUseCases":[{"title":"Competitor ad creative research","prompt":"Pull all public TikTok ads from the advertiser named 'Nike' shown in the UK over the last 30 days, sorted by most recent, up to 50 ads — I want to see what creatives they're running."},{"title":"Keyword-based ad trend monitoring","prompt":"Search the TikTok ad library for any ads with 'Black Friday' in the text, shown anywhere in Europe, from 2024-11-01 to 2024-11-30, sorted by create time descending, give me up to 60 results."},{"title":"Specific ad audit and status lookup","prompt":"Fetch the full details for these TikTok ad IDs: 1234567890, 9876543210, and 1122334455 — I need to see their status, audit results, and rejection info if any."}],"resultDescription":"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.","failureModes":["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"],"whenToPreferThis":"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.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-02T03:55:24.870Z","isFirstParty":false,"canonicalSlug":"tiktok-ads-library-scraper-x402-cc1e326d"}