# List Advertiser Ads Lists every ad run by a specific TikTok advertiser, identified by its exact registered entity name (e.g. "NIKE Retail B.V."). Returns raw ad payloads with country and date-range filtering. - Platform: [TikTok Ad Library](https://docs.upscrape.com/docs/platforms/tiktok-adlibrary) - Capability ID: `tiktok-adlibrary.advertiser-ads.list` - 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":{"advertiser_name":"NIKE Retail B.V.","business_id":"6876453864464188162","country":"ALL","limit":5},"capability":"tiktok-adlibrary.advertiser-ads.list"}' ``` ## Input | Field | Type | Required | Description | | --- | --- | --- | --- | | `advertiser_name` | `string` | Yes | The advertiser's exact registered entity name as shown in the TikTok Commercial Content Library (e.g. "NIKE Retail B.V."). Resolve names via the library's advertiser suggestions; matching is exact. | | `business_id` | `string` | No | TikTok advertiser business id (adv_biz_ids). Optional: carried through for parity with the upstream request; the filter is driven by advertiser_name. | | `country` | `string` | No | ISO-3166 alpha-2 country code, or "ALL" for all available regions (default: ALL). | | `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). | | `start_date` | `string` | No | Only ads shown on or after this date (YYYY-MM-DD). Default: 30 days ago. | ### Example input ```json { "advertiser_name": "NIKE Retail B.V.", "business_id": "6876453864464188162", "country": "ALL", "limit": 5 } ``` ## 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": "10K-100K", "first_shown_date": 1784414137000, "id": "1867527511007425", "image_urls": [ "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/ogREjeAtINjGgRVCzXODfDObq8AFB3fAXwzUQ8~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": 1784414137000, "name": "NIKE Retail B.V.", "rejection_info": null, "show_mode": 1, "sor_audit_status": "1", "spent": "", "title": "RIP THE SCRIPT | När du litar på magkänslan så äger du matchen.", "type": "2", "videos": [ { "cover_img": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/ogREjeAtINjGgRVCzXODfDObq8AFB3fAXwzUQ8~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", "video_url": "https://library.tiktok.com/api/v1/cdn/1784414613/video/[redacted:token]==/a7c72ee8-a80f-4e64-ba5e-90e49644a430?a=475769&bt=447&btag=e00088000&bti=PDU2NmYwMy86&ft=.NpOcInz7Th_DmDGXq8Zmo&l=202607190643337C9505A7BAEE8115E8B0&mime_type=video_mp4&rc=[redacted:token]%3D%3D&signature=[redacted:credential]&vvpl=1" } ] }, { "audit_status": "1", "estimated_audience": "100K-200K", "first_shown_date": 1784414137000, "id": "1869061192805506", "image_urls": [ "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/okGeiGgPfAIT3nJvCDNqUgBWWEBQFDDLxlIQiq~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": 1784414137000, "name": "NIKE Retail B.V.", "rejection_info": null, "show_mode": 1, "sor_audit_status": "1", "spent": "", "title": "RIP THE SCRIPT | Haaland och Tatum mediterar. Vänta och se.", "type": "2", "videos": [ { "cover_img": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/okGeiGgPfAIT3nJvCDNqUgBWWEBQFDDLxlIQiq~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", "video_url": "https://library.tiktok.com/api/v1/cdn/1784414613/video/[redacted:token]==/9634b697-5d15-42f2-86db-10b00e4fd9ff?a=475769&bt=380&btag=e000b8000&bti=PDU2NmYwMy86&ft=.NpOcInz7Th_DmDGXq8Zmo&l=202607190643337C9505A7BAEE8115E8B0&mime_type=video_mp4&rc=[redacted:token]%3D%3D&signature=[redacted:credential]&vvpl=1" } ] }, { "audit_status": "1", "estimated_audience": "500K-600K", "first_shown_date": 1784414137000, "id": "1867527511009505", "image_urls": [ "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o0mpoAfxEgBHeIIUYULeDCAnkJ6y0iETbBGBGX~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": 1784414137000, "name": "NIKE Retail B.V.", "rejection_info": null, "show_mode": 1, "sor_audit_status": "1", "spent": "", "title": "RIP THE SCRIPT | När du litar på magkänslan så äger du matchen.", "type": "2", "videos": [ { "cover_img": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o0mpoAfxEgBHeIIUYULeDCAnkJ6y0iETbBGBGX~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", "video_url": "https://library.tiktok.com/api/v1/cdn/1784414613/video/[redacted:token]==/cff7634f-016d-4ff2-9bad-19931ed48648?a=475769&bt=270&btag=e000b8000&bti=PDU2NmYwMy86&ft=.NpOcInz7Th_DmDGXq8Zmo&l=202607190643337C9505A7BAEE8115E8B0&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.advertiser-ads.list/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.advertiser-ads.list/llm.md)