# Search Ads Searches the TikTok Commercial Content Library by keyword. Returns raw ad payloads including creative, advertiser, run dates, targeted countries, and disclosed reach. Supports country and date-range filtering. - Platform: [TikTok Ad Library](https://docs.upscrape.com/docs/platforms/tiktok-adlibrary) - Capability ID: `tiktok-adlibrary.ad.search` - Cost: 10 credits per request - Maximum runtime: 120 seconds - Execute endpoint: `POST https://data.upscrape.com/execute` ## Request Use the exact public capability ID in the shared execute envelope. ```bash curl -X POST https://data.upscrape.com/execute \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"input":{"country":"ALL","limit":5,"query":"nike"},"capability":"tiktok-adlibrary.ad.search"}' ``` ## Input | Field | Type | Required | Description | | --- | --- | --- | --- | | `country` | `string` | No | ISO-3166 alpha-2 country code, or "ALL" for all available regions (default: ALL). The library covers EU/UK/EEA regions. | | `cursor` | `string` | No | Pagination cursor from a previous response's next_cursor. | | `end_date` | `string` | No | Only ads shown on or before this date (YYYY-MM-DD). Default: today. | | `limit` | `integer` | No | Maximum number of ads to return (default: 50). | | `query` | `string` | Yes | Search keyword or phrase (brand, product, slogan). | | `start_date` | `string` | No | Only ads shown on or after this date (YYYY-MM-DD). Default: 30 days ago. | ### Example input ```json { "country": "ALL", "limit": 5, "query": "nike" } ``` ## Response Successful output is returned in `results[0].data`. Raw platform output is intentionally open-ended and may evolve with the upstream source. ### Illustrative sample output This redacted fixture is an example, not a fixed response schema. ```json { "items": [ { "audit_status": "1", "estimated_audience": "0-1K", "first_shown_date": 1784237607000, "id": "1870908557528450", "image_urls": [ "https://p16-common-sign.tiktokcdn.com/tos-useast2a-i-photomode-euttp/6fe919413e04491ebaad8b42f3b28f2e~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=[redacted:credential]&x-expires=1784433600&x-signature=[redacted:credential]&t=4d5b0474&ps=13740610&shp=0c75dd76&shcp=9b759fb9&idc=sg1", "https://p16-common-sign.tiktokcdn.com/tos-useast2a-i-photomode-euttp/b49835fb967d42d78df3607de90a33c0~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=[redacted:credential]&x-expires=1784433600&x-signature=[redacted:credential]&t=4d5b0474&ps=13740610&shp=0c75dd76&shcp=9b759fb9&idc=sg1", "https://p16-common-sign.tiktokcdn.com/tos-useast2a-i-photomode-euttp/f7a12687beda49b3b6cb8b2384970e8a~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=[redacted:credential]&x-expires=1784433600&x-signature=[redacted:credential]&t=4d5b0474&ps=13740610&shp=0c75dd76&shcp=9b759fb9&idc=sg1" ], "impression": 0, "last_shown_date": 1784237607000, "name": "niketarase", "rejection_info": null, "show_mode": 2, "sor_audit_status": "1", "spent": "", "type": "2", "videos": [] }, { "audit_status": "1", "estimated_audience": "0-1K", "first_shown_date": 1784235284000, "id": "1870906107749890", "image_urls": [], "impression": 0, "last_shown_date": 1784235284000, "name": "nikestuehm", "rejection_info": null, "show_mode": 1, "sor_audit_status": "1", "spent": "", "title": "#fy #outfitinspo ", "type": "2", "videos": [ { "cover_img": "https://p16-common-sign.tiktokcdn.com/tos-useast2a-p-0037-euttp/oAyg0LDjMGUSslIqGgJGAd6UQeWJefGI7CQ7hG~tplv-noop.image?dr=18692&refresh_token=[redacted:credential]&x-expires=1784436176&x-signature=[redacted:credential]&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=0c75dd76&idc=sg1&VideoID=v26044gc0000d9cgqh7og65t7gqakb80", "video_url": "https://library.tiktok.com/api/v1/cdn/1784414564/video/[redacted:token]=/ca7a4095-f156-460d-aa35-dd501559f340?a=475769&bt=1076&btag=e000b0000&bti=PDU2NmYwMy86&ft=.NpOcInz7ThU9mDGXq8Zmo&l=202607190642443BE23421D2A879120ACD&mime_type=video_mp4&rc=[redacted:token]%3D%3D&signature=[redacted:credential]&vvpl=1" } ] }, { "audit_status": "1", "estimated_audience": "0-1K", "first_shown_date": 1784230236000, "id": "1870900817485890", "image_urls": [], "impression": 0, "last_shown_date": 1784230236000, "name": "pedroting1104", "rejection_info": null, "show_mode": 1, "sor_audit_status": "1", "spent": "", "title": "Nike Phantom Luna #FootballBoots #SoccerCleats #PhantomLuna #NikeFootball #Nike", "type": "2", "videos": [ { "cover_img": "https://p16-common-sign.tiktokcdn.com/tos-no1a-p-0037-no/o8WWQNZElKV3BIjESBFqAJFDgvkm0FvnfiVCde~tplv-noop.image?dr=18692&refresh_token=[redacted:credential]&x-expires=1784436182&x-signature=[redacted:credential]&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=0c75dd76&idc=sg1&VideoID=v24025gl0000d9b2ck7og65u6imtqmng", "video_url": "https://library.tiktok.com/api/v1/cdn/1784414564/video/[redacted:token]/f8d2de26-869b-4abd-b9e3-414a624b2ace?a=475769&bt=1429&btag=e000b8000&bti=PDU2NmYwMy86&ft=.NpOcInz7ThU9mDGXq8Zmo&l=202607190642443BE23421D2A879120ACD&mime_type=video_mp4&rc=[redacted:token]%3D%3D&signature=[redacted:credential]&vvpl=1" } ] } ], "next_cursor": "0:5:", "total_items": 5 } ``` ### Illustrative output fields Derived from the sample above for orientation only. These fields are not a fixed response schema. | Path | Observed type | Example | | --- | --- | --- | | `items` | `array` | 3 items | | `items` | `array` | 3 items | | `next_cursor` | `string` | 0:5: | | `total_items` | `integer` | 5 | ## Execution behavior A `200` response completed inline. A `202` response was queued; poll `GET /jobs/{id}` until the job reaches `completed` or `failed`. Use an `Idempotency-Key` when retrying must not create a duplicate logical job. See [jobs and results](https://docs.upscrape.com/docs/api/jobs), [errors and retries](https://docs.upscrape.com/docs/api/errors), and [idempotency](https://docs.upscrape.com/docs/api/idempotency). ## Machine-readable contract - [Capability OpenAPI 3.1](https://docs.upscrape.com/docs/platforms/tiktok-adlibrary/tiktok-adlibrary.ad.search/openapi.json) - [Platform OpenAPI 3.1](https://upscrape.com/scrapers/tiktok-adlibrary/openapi.json) - [Focused coding-agent prompt](https://upscrape.com/scrapers/tiktok-adlibrary/capabilities/tiktok-adlibrary.ad.search/llm.md)