POST
/v1/call/tiktok.ad_searchPreviewTikTok Ads Library search API
Only on TikTok.
The TikTok Ads Library search API searches TikTok's public Ads Library (ads shown in Europe) by keyword: advertiser, headline, videos and images, when each was first and last shown, and a bracket of people reached; newest first, 12 ads a page. This is the transparency record of ads, a different set from the Creative Center's Top Ads. One call costs 2 credits ($0.004 to $0.0067 depending on the pack); failed calls are free. Last tested 2026-10-17.
100 credits on sign-up, no card needed
2 creditsper call
Up to 12 per pageone page per call
2026-10-17last tested
1011 Bsample response, 1 item
Last updated:
Preview: this interface is not marked stable yet, so its parameters and fields may still change. It is charged like any other call, and a failed call is not charged.
Request and response
curl https://api.socialtoai.com/v1/call/tiktok.ad_search \ -H "Authorization: Bearer $SOCIALTOAI_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "running shoes" }'import osimport requestsresponse = requests.post( "https://api.socialtoai.com/v1/call/tiktok.ad_search", headers={"Authorization": f"Bearer {os.environ['SOCIALTOAI_KEY']}"}, json={ "query": "running shoes", },)print(response.json())# Connected over MCP? Ask in plain words.Use the TikTok Ads Library search interface (tiktok.ad_search) with query: running shoes.# Your AI calls the call tool with:{ "query": "running shoes"}200 OK1011 B2 credits
{ "op": "tiktok.ad_search", "platform": "tiktok", "status": "ok", "items": [ { "platform": "tiktok", "id": "…", "ref": "…", "approx": [], "type": "entry", "entry_type": "ad", "title": "…", "url": "https://example.com/…", "rank": null, "heat": null, "fields": { "format": null, "text": null, "landing_url": null, "advertiser": { "id": null, "name": "…", "url": null }, "images": [], "first_shown_at": "2026-09-29T00:00:00.000Z", "last_shown_at": "2026-09-30T00:00:00.000Z" } } ], "unavailable": ["fields.text", "fields.landing_url", "fields.advertiser.url"], "page": { "has_more": true, "cursor": "cur_…", "cursor_expires_at": "2026-10-12T22:42:45.000Z" }, "cost_credits": 2}- entry_type
- ad
- format
null- text
null- landing_url
null- first_shown_at
- 2026-09-29T00:00:00.000Z
- last_shown_at
- 2026-09-30T00:00:00.000Z
Names and text were removed from the sample; the numbers are as recorded.
Sample data1 of the 12 items recorded
2 parameters.
1 required.
Send them as a JSON body with POST. Your key goes in the Authorization header, never in the URL.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| query | string | Required | — | Search terms |
| cursor | string | Optional | — | Pass page.cursor from the last response to get the next page. |
The fields of each item.
What TikTok cannot give is marked.
| Field | Type | Meaning |
|---|---|---|
| items[].title | string | The entry's title or name. |
| items[].url | string | A link that opens it; null where the platform's list has none. |
| items[].rank | integer | Position on a board, from 1. |
| items[].heat | integer | The platform's heat score. |
| items[].fields.format | string | The ad's format: text, image or video. other is a format of the platform's own. |
| items[].fields.text | stringalways null | The ad's body text. |
| items[].fields.landing_url | stringalways null | Where a click on the ad leads. |
| items[].fields.advertiser.id | string | Advertiser ID. |
| items[].fields.advertiser.name | string | Advertiser's name. |
| items[].fields.advertiser.url | stringalways null | The advertiser's page on the platform. |
| items[].fields.images | string[] | Addresses of the ad's images. |
| items[].fields.first_shown_at | string | When the ad was first shown. |
| items[].fields.last_shown_at | string | When the ad was last shown. For an ad still running, when the platform last saw it. |
nullFields TikTok cannot giveRead null as “TikTok did not give this”, not as zero. These are always null on this call:
fields.textThe ad's body text.fields.landing_urlWhere a click on the ad leads.fields.advertiser.urlThe advertiser's page on the platform.
Every item also has platform, id, ref, approx and type; the response around the items is the same on every call. Response format
What to expect.
One call returns a page of up to 12 items. When page.has_more is true, send page.cursor back as cursor for the next page; each page costs 2 credits and a cursor works for 30 minutes.
A call that runs and finds nothing is a successful call: status is "empty", items is empty, and it costs 2 credits.
1 call per second per key, 5 after a purchase; going over is not charged. Rate limits
A failed call costs 0 credits and is never retried on its own. Error codes
Once connected over MCP, these questions use it.
Search TikTok's public Ads Library (ads shown in Europe) by keyword: running shoes.
2 creditscall {"op":"tiktok.ad_search","query":"running shoes"}
The interface of the same name on other platforms.
All platforms and pricesPOST
/v1/call/tiktok.ad_search{ "query": "running shoes" }2 creditsper callChange the op in the path. The response around the items keeps the same shape.
Questions.
Short answers.
Everything on TikTokDo I need a TikTok account or TikTok's own API access?
No. You only need a SocialToAI key. The call returns content and account information publicly visible on TikTok; you never sign in to TikTok or apply for anything there.
What does “Preview” mean here?
Preview: this interface is not marked stable yet, so its parameters and fields may still change. It is charged like any other call, and a failed call is not charged.