TikTok APIlibrary.tiktok.com ↗
Search TikTok's Commercial Content Library by advertiser or keyword. Get ad metadata, targeting details, creative formats, dates, and audience estimates via 3 endpoints.
What is the TikTok API?
This API exposes 3 endpoints for querying TikTok's Commercial Content Library, returning ad metadata such as creative format, first and last shown dates, estimated audience ranges, and media URLs. The search_ads endpoint accepts a query string against advertiser names or keywords, supports date-range filtering via Unix timestamps, and paginates via a search_id token. The get_ad_details endpoint returns per-ad targeting data including age, gender, and location breakdowns.
curl -X GET 'https://api.parse.bot/scraper/8a656d95-c7a6-406d-b28e-6b6f91cf8493/search_ads?limit=12&query=nike&offset=0®ion=all&sort_by=last_shown_date%2Cdesc' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace library-tiktok-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""TikTok Ad Library: search ads, drill into details, list regions."""
from parse_apis.tiktok_ad_library_api import TikTokAdLibrary, Sort, AdNotFound
client = TikTokAdLibrary()
# List supported regions for filtering
for region in client.regions.list(limit=5):
print(region.code, region.name)
# Search ads by keyword, sorted newest first
ad = client.adsummaries.search(query="nike", sort_by=Sort.NEWEST, limit=1).first()
if ad:
print(ad.advertiser_name, ad.creative_format, ad.last_shown_date)
# Drill into full detail with targeting info
detail = ad.details()
print(detail.advertiser_registry_location, detail.estimated_audience)
for loc in detail.targeting.locations:
print(loc.region, loc.impressions)
# Direct fetch by ad_id with error handling
try:
full = client.ads.get(ad_id="1867460299162625")
print(full.advertiser_name, full.targeting.target_audience_size)
except AdNotFound as exc:
print(f"Ad not found: {exc}")
print("exercised: regions.list / adsummaries.search / AdSummary.details / ads.get")
Search the TikTok Ad Library for ads matching a query (advertiser name or keyword). Returns paginated results with ad metadata including creative format, dates, audience estimates, and media URLs. Paginates via offset+search_id; the search_id from the first response must be passed on subsequent pages.
| Param | Type | Description |
|---|---|---|
| limit | integer | Number of results per page (max 50) |
| queryrequired | string | Search query (advertiser name or keyword) |
| offset | integer | Pagination offset (0-based). Requires search_id from a previous response for values > 0. |
| region | string | Region/country code filter (e.g. 'FR', 'DE', 'GB') or 'all' for all regions. Use get_supported_regions for the full list of accepted codes. |
| sort_by | string | Sort order: 'last_shown_date,desc' or 'last_shown_date,asc' |
| end_time | integer | End of date range as Unix timestamp (seconds). Defaults to now. |
| search_id | string | Search ID returned from a previous search_ads call. Required when offset > 0 to paginate through results. |
| start_time | integer | Start of date range as Unix timestamp (seconds). Defaults to 1 year ago. |
{
"type": "object",
"fields": {
"ads": "array of ad objects with ad_id, advertiser_name, creative_format, first_shown_date, last_shown_date, estimated_audience, video_thumbnail_url, video_url, image_urls",
"limit": "integer current page size",
"query": "string the query used",
"total": "integer total number of matching ads",
"offset": "integer current offset",
"region": "string the region filter used",
"has_more": "boolean indicating if more pages are available",
"search_id": "string identifier for paginating subsequent requests"
},
"sample": {
"data": {
"ads": [
{
"ad_id": "1867440643847297",
"video_url": "",
"image_urls": [
"https://p16-common-sign.tiktokcdn.com/example.jpeg"
],
"advertiser_name": "endikerenike",
"creative_format": "image",
"last_shown_date": "2026-06-09",
"first_shown_date": "2026-06-09",
"estimated_audience": "1K-10K",
"video_thumbnail_url": ""
}
],
"limit": 12,
"query": "nike",
"total": 1000,
"offset": 0,
"region": "all",
"has_more": true,
"search_id": "20260611160335121F6B5CC281C4708A89"
},
"status": "success"
}
}About the TikTok API
What the API Covers
The TikTok Ad Library API surfaces data from TikTok's publicly accessible Commercial Content Library. search_ads accepts a required query string (advertiser name or keyword) and returns a paginated list of matching ads. Each result includes ad_id, advertiser_name, creative_format (video or image), first_shown_date, last_shown_date, estimated_audience, and media thumbnail URLs. Results can be filtered by region, sorted by last_shown_date ascending or descending, and bounded by start_time and end_time as Unix timestamps.
Pagination and Search Sessions
Pagination requires a two-step pattern. The first call to search_ads returns a search_id alongside has_more and total. For any subsequent page, pass the same search_id together with an incremented offset. Skipping the search_id on offset > 0 will not produce correct results. The limit parameter caps at 50 per page.
Ad Details and Targeting
get_ad_details takes a single ad_id (obtained from search_ads) and returns a fuller record: sponsor, targeting (broken down into locations, age, and gender), video_url, image_urls, estimated_audience, and ISO-format first_shown_date / last_shown_date. The optional lang parameter localizes certain string fields. The get_supported_regions endpoint returns the full list of region code and name pairs accepted by search_ads's region parameter, and also supports lang for localized region names.
The TikTok API is a managed, monitored endpoint for library.tiktok.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when library.tiktok.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official library.tiktok.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track when a competitor's TikTok ads first and last ran using
first_shown_dateandlast_shown_datefromsearch_ads. - Identify which creative formats (video vs. image) a brand favors by aggregating
creative_formatacross search results. - Filter ad activity to a specific country using the
regionparameter and data fromget_supported_regions. - Pull targeting breakdowns (age, gender, location) for a known ad ID via
get_ad_detailsto analyze audience strategy. - Monitor ad volume trends over time by querying
search_adswithstart_timeandend_timedate windows. - Build an advertiser watchlist by periodically querying each brand name and comparing
totalresult counts across periods. - Collect
video_urlandimage_urlsfields fromget_ad_detailsto archive creative assets for a given campaign.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does TikTok have an official developer API for its Ad Library?+
What targeting data does `get_ad_details` return?+
targeting object with three sub-fields: locations (region-level audience targeting), age (age bracket breakdown), and gender. It also returns an estimated_audience string indicating the audience size range. Targeting data reflects what the advertiser disclosed in the public library.Does the API cover TikTok regions outside Europe?+
get_supported_regions endpoint currently returns European region codes. The search_ads endpoint accepts 'US' and 'all' as region values, but the supported region list is oriented toward EU coverage. You can fork this API on Parse and revise it to extend region handling if your use case requires broader geographic filtering.Can I retrieve engagement metrics like views, likes, or shares for an ad?+
first_shown_date, last_shown_date), estimated_audience ranges, creative format, and targeting. Engagement data is not part of TikTok's public Ad Library disclosure. You can fork this API on Parse and revise it to add an endpoint if TikTok exposes that data in the future.How does pagination work across multiple pages of results?+
search_ads call returns a search_id. For pages beyond the first, pass that same search_id along with an incremented offset. The has_more boolean tells you whether additional pages exist, and total gives the full result count for the query.