---
title: "TikTok Ad Library Search API"
method: GET
path: "/v1/ad-library/tiktok/search"
tags: ["TikTok Ad Library"]
---

# TikTok Ad Library Search API

`GET /v1/ad-library/tiktok/search`

## Request

- Base URL: `https://api.captapi.com`
- URL: `https://api.captapi.com/v1/ad-library/tiktok/search`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Search TikTok Commercial Content Library — relevance-filtered, uniform null schema (2 credits native, 5 via fallback).

Search TikTok's Commercial Content Library (library.tiktok.com / EU DSA) by keyword. Local keyword matching is case-insensitive whole-word match=any|all (hair ≠ wheelchair). Envelope uses candidatesScanned / truncated (true when literalMatches > totalReturned); each hit has matchedFrom as a string array of matched fields. platform is tiktok (library=dsa). media[] are objects with url/type/expiresAt when signed. Ads share a uniform key set — withheld fields are null, not missing. firstShown/lastShown are omitted (DSA list XHR stamps scrape/serve times, not run dates) — use /tiktok/ad-details for calendar-day ISO dates. advertiser is always {id,name,url,logo,location}; advertiser.logo is null in practice because the library publishes no advertiser logo (the key stays for the shared ad-library schema). 2 credits when the native path returns results; 5 credits when the fallback path serves them; empty results are 0 credits. Native-only by default (the fallback path is disabled). A miss is a retryable 503 at 0 credits. When the fallback is enabled and the native fetch is slow, it starts beside it (15s for one-page fetches, later for larger limits) and the first useful answer wins. country default GB (US often empty). Coverage is ads shown in the last 30 days (the library's default window): an ad that stopped running more than 30 days ago drops out of results, so a keyword that matched last month can return empty today — use /v1/ad-library/tiktok/ad-details with the ad id for older ads. For brand performance use /v1/ad-library/tiktok/top-ads.

Docs: https://captapi.com/apis/tiktok-ad-library-search

## Query parameters

- `q` string, required
- `country` string
- `match` string
- `limit` integer
- `cache` boolean

## Response `200`

Success. The data object for this endpoint.

- object
  - `success` unknown, required
  - `data` object, required
    - `query` string: The search query you sent.
    - `country` string: Country for the request context. On popular-creators top-level: ISO feed market you queried (e.g. US) — not each creator's home country (see region).
    - `totalReturned` integer: Number of items returned in this response.
    - `ads` object[]
      - `platform` string: Platform identifier for this response (matches the endpoint's platform).
      - `id` string: Id of this ads item.
      - `url` string: Canonical URL of the item.
      - `text` string: Text content.
      - `adFormat` string: Format of the ad creative.
      - `firstShown` string: When the ad was first shown.
      - `lastShown` string: When the ad was last shown.
      - `impressions` string: Estimated ad impressions.
      - `advertiser` object: Advertiser running the ad.
        - `name` string
        - `location` string
      - `media` string[]: Array of {url, type, expiresAt}. expiresAt is second-precision from x-expires / VExpiration / expire=; null when the URL is unsigned (library.tiktok.com often has no expiry param). width/height/durationSeconds are not on this surface.
      - `impressionsRange` object: Parsed impressions as {min, max, raw}. Prefer this for sorting; impressions stays the Meta display string. Usually null for commercial ads.
        - `min` integer
        - `max` integer
        - `raw` string

## Other responses

- `400`: Bad request: wrong platform URL, unknown endpoint, or an invalid parameter value. Not billed.
- `401`: Missing, invalid or revoked API key. Not billed.
- `402`: Not enough credits for this request. Not billed.
- `404`: The resource does not exist or is not public. Not billed.
- `422`: A required parameter is missing or has the wrong type. Not billed.
- `429`: Rate limit reached. Wait for Retry-After seconds. Not billed.
- `502`: The platform could not be reached or returned nothing usable. Retryable, not billed. 503 and 504 use the same envelope.

---

[API](https://skmtc.dev/captapi/apis/captapi-api.md) · [All operations](https://skmtc.dev/captapi/apis/captapi-api/llms.txt) · [OpenAPI document](https://skmtc.dev/captapi/apis/captapi-api/revisions/c9b9ac5ff1bd?raw)