TikTok Ad Library API · Endpoint

TikTok Ad Library Ad Detail API

Q: What do I send?

Send ad_id. The input fields below list every option with its type and limits.

Q: Can my AI agent call it?

Yes, over MCP: the agent finds tiktok-adlibrary.ad.detail.get, checks its price and runs it with the same credits as the REST API.

Get one ad in full: its creative, call to action and link, the advertiser and who paid for it, targeting by age, gender and country, and reach.

10 credits per call
Failed calls are free
Updated 12 Oct 2026
tiktok-adlibrary.ad.detail.get

Start free, 100 credits API reference

Response completed

{  "display_mode": "enhanced",  "ad": {    "name": "NIKE Retail B.V.",    "title": "Schulanfang mit Nike",    "advertising_objective": "Sales",    "audit_status": "1",    "call_to_action": "Shop now",    "estimated_audience": "10K-100K",    "external_url": "https://www.nike.com/de/w/back-to-school-schuhe-840ikzy7ok?utm_source=tiktok&utm_medium=paid",    "first_shown_date": 1787356800000,    "id": "1874222777792674",    "impression": 0,    "last_shown_date": 1788134400000,    "rejection_info": null,    "show_mode": 1,    "sor_audit_status": "1",    "spent": "",    "subject": "Apparel & Accessories",    "type": "2"  },  "advertiser": {    "name": "NIKE Retail B.V.",    "adv_biz_ids": "6876453864464188162",    "registry_location": "Netherlands",    "sponsor": "INITIATIVE MEDIA B.V.",    "tt_user": null  },  "targeting": {    "audience": "No",    "audience_exclude": "No",    "creator_interactions": "",    "high_spending_power": "No",    "interest": "",    "target_audience_size": "14.9M-18.3M",    "video_interactions": "",    "location": {      "total_impressions": "10K-100K",      "total_region": 1,      "data": [        {          "impressions": "53K",          "region": "DE",          "breakdowns": [            {              "age": "18-24",              "gender": "MALE",              "impressions": "7K"            },            {              "age": "18-24",              "gender": "FEMALE",              "impressions": "18K"            }          ]        }      ]    },    "age": [      {        "13-17": false,        "18-24": true,        "25-34": true,        "35-44": true,        "45-54": false,        "55+": false,        "region": "DE"      }    ],    "cities": [],    "countries": [      "DE"    ],    "device_models": [],    "gender": [      {        "female": true,        "male": true,        "region": "DE",        "unknown": true      }    ],    "languages": [],    "operating_systems": [      "ALL"    ],    "provinces": []  }}

Try it live, free

Input

What you send

The input object of the request, with every field the endpoint accepts.

Field	Type	Required	What it does	Example
ad_id	string	yes	The ad's ID, from ad search or an advertiser's ads.	1874222777792674

Response

Fields it returns

What each record in the response holds, with the values from the sample above.

Field	Type	What it is	Example
targeting.age[].13-17	boolean	Whether the ad was aimed at ages 13 to 17.	false
targeting.age[].18-24	boolean	Whether the ad was aimed at ages 18 to 24.	true
targeting.age[].25-34	boolean	Whether the ad was aimed at ages 25 to 34.	true
targeting.age[].35-44	boolean	Whether the ad was aimed at ages 35 to 44.	true
targeting.age[].45-54	boolean	Whether the ad was aimed at ages 45 to 54.	false
targeting.age[].55+	boolean	Whether the ad was aimed at ages 55 and over.	false
targeting.age[].region	string	The country these age groups apply to.	DE
ad	object	The ad's details.	17 fields
ad.title	string	The ad's text.	Schulanfang mit Nike
ad.call_to_action	string	The ad's button text.	Shop now
ad.advertising_objective	string	What the advertiser set the ad to achieve.	Sales
ad.estimated_audience	string	TikTok's range for how many people the ad reached.	10K-100K
ad.external_url	string	Where the ad links to.	https://www.nike.com/de/w/back-to-school-schuhe-840ikzy7ok?utm_…
ad.audit_status	string	TikTok's review status code for the ad.	1
ad.first_shown_date	integer	When the ad was first shown, as a Unix timestamp in milliseconds.	1,787,356,800,000
ad.id	string	TikTok's ID for the ad, used by the ad detail endpoint.	1874222777792674
ad.impression	integer	Impressions as a number, when TikTok gives one; often 0.	0
ad.last_shown_date	integer	When the ad was last shown, as a Unix timestamp in milliseconds.	1,788,134,400,000
ad.name	string	The advertiser's name.	NIKE Retail B.V.
ad.rejection_info	null	Why TikTok rejected the ad, when it did.	null
ad.show_mode	integer	TikTok's code for how the ad is shown.	1
ad.sor_audit_status	string	A second review status code TikTok gives the ad.	1
ad.spent	string	Amount spent on the ad, when TikTok shows it.
ad.subject	string	The ad's topic.	Apparel & Accessories
ad.type	string	TikTok's code for the kind of ad.	2
advertiser	object	The advertiser's details.	5 fields
advertiser.name	string	The advertiser's name.	NIKE Retail B.V.
advertiser.sponsor	string	Who paid for the ad.	INITIATIVE MEDIA B.V.
advertiser.registry_location	string	Where the advertiser is registered.	Netherlands
advertiser.adv_biz_ids	string	TikTok's IDs for the advertiser.	6876453864464188162
advertiser.tt_user	null	The advertiser's TikTok account, when linked.	null
display_mode	string	How much detail TikTok shows for the ad, such as enhanced.	enhanced
targeting	object	Who the ad was aimed at.	16 fields
targeting.age	array	Age groups the ad was aimed at.	1 records
targeting.audience	string	Whether the ad used a custom audience.	No
targeting.audience_exclude	string	Whether the ad excluded a custom audience.	No
targeting.cities	array	Cities the ad was aimed at.	empty in this sample
targeting.countries	array	Countries the ad was aimed at.	DE
targeting.creator_interactions	string	Creator interaction targeting, when the ad used it.
targeting.device_models	array	Device models the ad was aimed at.	empty in this sample
targeting.gender	array	Genders the ad was aimed at.	1 records
targeting.gender[].female	boolean	Whether the ad was aimed at women.	true
targeting.gender[].male	boolean	Whether the ad was aimed at men.	true
targeting.gender[].region	string	The country these genders apply to.	DE
targeting.gender[].unknown	boolean	Whether the ad was aimed at people of unknown gender.	true
targeting.high_spending_power	string	Whether the ad was aimed at people TikTok sees as big spenders.	No
targeting.interest	string	Interests the ad was aimed at.
targeting.languages	array	Languages the ad was aimed at.	empty in this sample
targeting.location	object	Where the ad was seen, with impressions by region, age and gender.	3 fields
targeting.location.data	array	Impressions by country, split by age and gender.	1 records
targeting.location.total_impressions	string	TikTok's range for how often the ad was shown.	10K-100K
targeting.location.total_region	integer	How many countries the ad ran in.	1
targeting.operating_systems	array	Phone systems the ad was aimed at.	ALL
targeting.provinces	array	Regions the ad was aimed at.	empty in this sample
targeting.target_audience_size	string	TikTok's range for the size of the target audience.	14.9M-18.3M
targeting.video_interactions	string	Video interaction targeting, when the ad used it.

REST API · MCP server

Call it from your code, or ask your agent

Set UPSCRAPE_API_KEY to your key and copy a working request.

curl --request POST \  --url https://data.upscrape.com/execute \  --header "Authorization: Bearer $UPSCRAPE_API_KEY" \  --header "Content-Type: application/json" \  --header "Prefer: wait=30" \  --data '{  "capability": "tiktok-adlibrary.ad.detail.get",  "input": {    "ad_id": "1874222777792674"  }}'

import jsonimport osimport requestspayload = json.loads(r'''{  "capability": "tiktok-adlibrary.ad.detail.get",  "input": {    "ad_id": "1874222777792674"  }}''')response = requests.post(    "https://data.upscrape.com/execute",    headers={        "Authorization": f"Bearer {os.environ['UPSCRAPE_API_KEY']}",        "Content-Type": "application/json",        "Prefer": "wait=30",    },    json=payload,)response.raise_for_status()print(json.dumps(response.json(), indent=2))

const response = await fetch("https://data.upscrape.com/execute", {  method: "POST",  headers: {    "Authorization": `Bearer ${process.env.UPSCRAPE_API_KEY}`,    "Content-Type": "application/json",    "Prefer": "wait=30",  },  body: JSON.stringify({  "capability": "tiktok-adlibrary.ad.detail.get",  "input": {    "ad_id": "1874222777792674"  }}),});if (!response.ok) {  throw new Error(`Upscrape request failed: ${response.status}`);}console.log(JSON.stringify(await response.json(), null, 2));

In your AI agent Claude · Cursor · any MCP client

1Add the Upscrape MCP server

https://data.upscrape.com/mcp

2Ask for the data in plain words

Use Upscrape to open TikTok ad 1874222777792674 and tell me who it targets by age and gender, the country, the objective and who paid for it.

The agent finds the endpoint, shows you the price, and runs it with your credits.

TikTok Ad Library

More from the TikTok Ad Library API

Same data, other platforms

The same data from other platforms

Facebook Ad LibraryAd detail1 credit

Questions

TikTok Ad Library Ad Detail API FAQ

The short answers. The docs have the long ones.

Still have a question? Talk to the people who build the endpoints.

Book a call [email protected]

How much does the TikTok Ad Library Ad Detail API cost?

10 credits per successful call, shown before it runs. You buy credits once, and paid credits never expire.

What do I send?

Send ad_id. The input fields below list every option with its type and limits.

Do I need a TikTok Ad Library login?

No. It reads public TikTok Ad Library data; nothing runs on your account.

Can my AI agent call it?

Yes, over MCP: the agent finds tiktok-adlibrary.ad.detail.get, checks its price and runs it with the same credits as the REST API.

Get started

Your first TikTok Ad Library call is free.

Up to 100 free credits to start, no card needed.

Start building for free Book a call