↑ ↓ to move ↵ to open
TikTok Ad Library API reference

TikTok Ad Library Ad Detail

tiktok-adlibrary.ad.detail.get

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.

At a glance

Endpoint ID
tiktok-adlibrary.ad.detail.get
Price
10 credits per call; failed calls are free
Runs for up to
120 seconds
Request
POST /execute
Run an endpoint
MCP tool when pinned
tiktok-adlibrary__ad__detail__get
Pin tools
OpenAPI
openapi.json
Download

Request

Send the endpoint ID as capability and its fields as input. Set UPSCRAPE_API_KEY to your key first.

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"  }}'

Input

FieldTypeRequiredWhat it doesExample
ad_id string yes The ad's ID, from ad search or an advertiser's ads. 1874222777792674

Response

A finished call answers with HTTP 200; the data is in results[0].data, and billing.credits_charged is what it cost. A call still running after the wait answers 202: see jobs and results.

This is results[0].data from a real run:

results[0].data
{  "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": []  }}

Fields

FieldTypeWhat it isExample
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.

If a call fails

A failed call costs nothing. The response carries an error.code you can branch on; Errors and retries lists every code and which ones to retry.

Other TikTok Ad Library endpoints

Something missing or unclear? Ask the team that builds the TikTok Ad Library endpoints.