# TikTok Commercial Content Library: GET /v1/tiktok/ads > Search ads in TikTok's Commercial Content Library by keyword or advertiser, in one country of the EEA, the UK or Switzerland, within a date window. Base URL: `https://api.publicadsapi.com` · Auth: `authorization: Bearer ` · Web version: https://publicadsapi.com/docs/api/tiktok - **Ads a page**: up to 36. One page per call; `next_cursor` for more. - **Credits**: 1 credit a page. Only when the page has ads. Empty pages, errors and the sandbox are free. - **Covers**: The EEA, the UK and Switzerland. Search by `q` or `advertiser`. ## Request cURL: ```bash curl "https://api.publicadsapi.com/v1/tiktok/ads?q=pottery&country=GB" \ -H "authorization: Bearer $PADS_API_KEY" ``` Node.js: ```js const res = await fetch('https://api.publicadsapi.com/v1/tiktok/ads?q=pottery&country=GB', { headers: { authorization: `Bearer ${process.env.PADS_API_KEY}` }, }); const result = await res.json(); if (!res.ok) throw new Error(`${result.error.code}: ${result.error.message}`); console.log(result.ads.length, 'ads; next page:', result.next_cursor); ``` Python: ```python import os import requests res = requests.get( "https://api.publicadsapi.com/v1/tiktok/ads?q=pottery&country=GB", headers={"authorization": f"Bearer {os.environ['PADS_API_KEY']}"}, timeout=60, ) result = res.json() if not res.ok: raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}") print(len(result["ads"]), "ads; next page:", result["next_cursor"]) ``` ## Parameters Every filter here is the library's own, run by the platform, so pages are full and `total_estimate` counts what matches. Anything else is `400 INVALID_INPUT` naming it. - `Authorization` (header, string, required): `Bearer `. Keys starting `pads_test_` get the sandbox (sample ads, never charged); keys starting `pads_live_` read the platform and use credits. - `q` (query, string, send one of q, advertiser): A keyword. It also matches creators' posts that mention a brand; for one advertiser's ads, use `advertiser`. Also accepted as `query` or `keyword`. Example: `q=pottery` - `advertiser` (query, string, send one of q, advertiser): An advertiser's exact name, as TikTok shows it (the `advertiser.name` of any of its ads). TikTok matches advertisers by name: it can't search by business id. Not yet confirmed against TikTok's live library (October 2026); if it brings nothing back, search the name with `q`. Example: `advertiser=Fabrikam Studio` - `country` (query, string): Where the ad was shown: a country of the EEA, `GB` or `CH`. TikTok's library covers no others, so there are no US ads. Default `GB`. Also accepted as `country_code`. - `sort` (query, string): `last_shown`: most recently seen first. `first_shown`: most recently started first. One of: `last_shown`, `first_shown`. Default `last_shown`. - `date_from` (query, YYYY-MM-DD): Ads shown on or after this day, `YYYY-MM-DD`. Default a year before `date_to`. Example: `date_from=2026-01-01` - `date_to` (query, YYYY-MM-DD): Ads shown on or before this day, `YYYY-MM-DD`. Not before `date_from`. Default today. Example: `date_to=2026-10-21` - `cursor` (query, string): The `next_cursor` of the page before. Send it with exactly the same other parameters: a cursor from a different search is `400 INVALID_INPUT`. - `include` (query, comma-separated): `raw` adds each ad's own record from the platform as `raw`, for fields we don't map. Values: `raw`. Example: `include=raw` ## Response 200 OK (sandbox; the first ad of the page): ```json { "platform": "tiktok", "query": { "q": "pottery", "advertiser": null, "country": "GB", "sort": "last_shown", "date_from": "2025-10-21", "date_to": "2026-10-21" }, "ads": [ { "id": "tiktok_7400000000000000001", "platform": "tiktok", "platform_ad_id": "7400000000000000001", "library_url": "https://library.tiktok.com/ads/detail/?ad_id=7400000000000000001", "advertiser": { "id": "7000000000000000001", "name": "Fabrikam Studio", "domain": null, "library_url": null }, "status": "unknown", "first_shown": "2026-08-20T00:00:00Z", "last_shown": "2026-10-16T00:00:00Z", "format": "video", "text": { "headline": "Glaze your own mug this weekend", "body": null, "description": null, "cta": "Book now" }, "text_source": "platform", "link_url": "https://fabrikam-studio.example/workshops", "media": [ { "type": "video", "url": "https://example.com/sandbox-media/tiktok-1.mp4", "preview_url": "https://example.com/sandbox-media/tiktok-1.jpg", "width": 720, "height": 1280 } ], "placements": [ "tiktok" ], "regions": [ "GB" ], "metrics": { "impressions": null, "reach": { "min": 1000, "max": 10000 }, "spend": null }, "variants": null } ], "total_estimate": 3, "has_more": false, "next_cursor": null, "credits_used": 0, "credits_remaining": null } ``` ## What TikTok ads carry - `advertiser.name` is the advertiser as TikTok shows it: pass it as `advertiser` for that advertiser's ads only. `advertiser.id` is TikTok's business id (TikTok can't search by it). - `metrics.reach` is TikTok's audience estimate as a range: "10K-100K" is `{ "min": 10000, "max": 100000 }`. - `regions` is the country the ad was shown in. `status` is `unknown`: TikTok gives first and last shown days. - Most ads are `video`, with a still in `media[].preview_url`. ## Limits to know - TikTok's library covers ads shown in the EEA, the UK and Switzerland only. There are no US ads in it, so `country` must be one of those (default `GB`). - TikTok needs a date window: `date_from` and `date_to` default to the last 12 months. - A keyword also matches creators' posts that mention a brand. For one advertiser's ads, use `advertiser` with its exact name (not yet confirmed against TikTok's live library, October 2026; if it brings nothing back, search the name with `q`). - A page holds up to 36 ads (three of TikTok's pages of 12). ## One ad with its detail `GET /v1/ads/{id}` with an `id` from this search (1 credit). Reach per country, who paid, and the targeting used (ages, genders, places, and whether audience and interest targeting were used). The same for UK ads as for EU ones. The rest of TikTok's record (age and gender breakdowns, the advertiser's registered country) is in `raw` with `include=raw`. See [One ad](https://publicadsapi.com/docs/api/ads.md). See also: [Google](https://publicadsapi.com/docs/api/google.md) · [LinkedIn](https://publicadsapi.com/docs/api/linkedin.md)