Data reference - Adriel Knowledge Base

Introduction

TikTok Ads is TikTok’s paid advertising platform, used to run mobile-first video ads across TikTok’s short-form feed, in-feed placements, and partner properties. It supports CPC, CPM, oCPM, and CPV payment models across awareness, traffic, app-install, conversion, lead-generation, and product-sales objectives. The connector imports campaign structure, performance metrics, and conversion data through the TikTok Marketing API. As a marketing connector, metrics, breakdowns, and currencies are standardized so widgets can aggregate across sources without additional configuration. To connect this data source, see How to connect TikTok Ads to Adriel.

Data refresh strategy

Architecture data

Architecture covers ad accounts, campaigns, ad sets, and ads. It refreshes every 6 hours, on the hour (UTC). On data source creation, the cache fills with 730 days of historical data for ad account, campaign, ad set, and ad.

Reports data

Reports include daily performance metrics for ad accounts, campaigns, ad sets, and ads, plus per-ad-account breakdowns for gender, age, location, platform placement, OS, and country. Cache-only. Report data comes from cached daily performance snapshots. Dashboard queries always read from the last snapshot, never live from TikTok. Refresh schedule. Reports refresh on three schedules:

5:00 PM UTC daily — syncs the last 9 days for ad account, campaign, ad set, and ad, plus per-ad-account gender, age, location, platform placement, OS, and country
8:40 PM, 11:40 PM, 2:40 AM, 6:40 AM, 8:40 AM, 11:40 AM, and 2:40 PM UTC — syncs the last 3 days for the same set
3:00 PM UTC, every 2 days — syncs the last 30 days for the same set

Data is reliable within the cache sync period. Data outside this range may be incomplete or inaccurate due to legacy caching behavior.

Metrics based on uniqueness, such as reach, can be overvalued when viewed over date periods longer than one day, because uniqueness is computed per snapshot rather than across the full range.

Architecture levels

Ad account → Campaign → Ad set → Ad

Date range limits

Breakdown	Max range
Daily	93 days
Weekly	1 year
Monthly	2 years

Only the last 3 years of data can be fetched, regardless of breakdown.

Metrics

How to read the columnsData type uses Adriel’s vocabulary — Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean. API Key in code style like impressions is the literal TikTok Marketing API field; italic marks a value Adriel computes, derives, or parses (for example UTM values read from the landing page URL) rather than reading from a single API field. Some raw fields back several metrics — for example landing_page_url backs every UTM metric and engagements backs several engagement metrics — so the same key can appear on multiple rows; that’s the shared source field, not a duplicated entry. Currency values are reported in each ad account’s configured TikTok currency and converted to the workspace currency on demand using the current day’s exchange rate.

Basic

Metric	Description	Data type	API Key
Channel Type	TikTok-specific subtype for the selected campaign or ad when available.	Text	Adriel-derived
Creative Image	Unique visual identifier used to group identical or near-identical creatives.	Text	Adriel-derived
Creative Type	Format of the creative, such as image or video.	Text	Adriel-derived
Goal	Optimization goal configured for the selected campaign or ad group when available.	Array	Adriel-derived
Lifetime Budget	Lifetime budget amount when the selected campaign or ad group uses a total budget.	Currency	`budget`, `budget_mode`
Result Indicator	Primary result label used to identify the reported outcome.	Text	Adriel-derived
Results	Primary results reported for the selected objective.	Text	Adriel-derived
Title	Title text reported for the ad creative when available.	Array	Adriel-derived

Campaign Attributes

Metric	Description	Data type	API Key
Ad Account Name	The name of the TikTok ad account.	Text	`name`, `advertiser_name`
Ad Name	The name of the TikTok ad.	Text	`ad_name`
Ad Set Name	The name of the TikTok ad group.	Text	`adgroup_name`
Ad Spend	Sum of your total ad spend.	Currency	`spend`, `cost`
Bid Cap	Bid amount configured for the ad group when TikTok provides one.	Currency	`bid_price`
Bid Strategy	Bid strategy or delivery method used by the selected campaign or ad group.	Text	`deliveryMethod`, `bid_type`
Budget	Budget setting reported for the selected campaign or ad group.	Text	`budget`, `budget_mode`
Campaign Name	The name of the TikTok campaign.	Text	`campaign_name`
Creative URL	Primary image or video URL associated with the ad creative.	URL	`video.preview_url`, `images.image_url`, `spark.video_info.preview_url`
Daily Budget	Daily budget amount when the selected campaign or ad group uses a daily budget.	Currency	`budget`, `budget_mode`
Ends	The scheduled end date of the campaign or ad group, when one is set.	Date	Adriel-derived
Is Active	Whether the selected campaign, ad group, or ad is currently active.	Text	Adriel-derived
Landing URL	Destination URLs that people can reach from the ad.	URL	`landing_page_url`, `landing_page_urls`
Objective	The advertising objective selected for the campaign, ad group, or ad.	Text	`objective_type`
Starts	The scheduled start date of the campaign or ad group.	Date	Adriel-derived
Status	The current delivery and review status of the selected campaign, ad group, or ad.	Text	`operation_status`, `secondary_status`
Status Text	A text label describing the current delivery status of the selected campaign, ad group, or ad.	Text	Adriel-derived
UTM Campaign	UTM campaign value found in the ad landing page URL.	Text	`landing_page_url`, `landing_page_urls`
UTM Content	UTM content value found in the ad landing page URL.	Text	`landing_page_url`, `landing_page_urls`
UTM Medium	UTM medium value found in the ad landing page URL.	Text	`landing_page_url`, `landing_page_urls`
UTM Source	UTM source value found in the ad landing page URL.	Text	`landing_page_url`, `landing_page_urls`
UTM Term	UTM term value found in the ad landing page URL.	Text	`landing_page_url`, `landing_page_urls`

UTM values are parsed by Adriel, not returned by TikTok. Adriel reads the UTM query parameters from each ad’s landing page URL and exposes them as both metrics (for rollup) and breakdowns (for grouping).

Campaign Structure

Metric	Description	Data type	API Key
Ad Account ID	The TikTok identifier of the ad account.	Text	`advertiser_id`
Ad ID	The TikTok identifier of the ad.	Text	`ad_id`
Ad Set ID	The TikTok identifier of the ad group.	Text	`adgroup_id`
Campaign ID	The TikTok identifier of the campaign.	Text	`campaign_id`
Channel	Normalized TikTok subchannel classification for the selected campaign or ad.	Array	Adriel-derived

Computed Metric

These are calculated by Adriel from other metrics; they have no single underlying TikTok field.

Metric	Description	Data type	API Key
Frequency	Impressions divided by reach.	Ratio	Adriel-computed
ROAS	Return on ad spend — conversion value divided by spend.	Percentage	Adriel-computed
Video Played To 100% (%)	Plays reaching 100% completion as a share of total plays.	Percentage	Adriel-computed
Video Played To 25% (%)	Plays reaching 25% completion as a share of total plays.	Percentage	Adriel-computed
Video Played To 50% (%)	Plays reaching 50% completion as a share of total plays.	Percentage	Adriel-computed
Video Played To 75% (%)	Plays reaching 75% completion as a share of total plays.	Percentage	Adriel-computed
View Rate	Video views as a share of impressions.	Percentage	Adriel-computed

ROAS is shown as a percentage. Adriel displays TikTok ROAS as a percentage (for example 358%), where TikTok’s own UI shows the same value as a decimal (3.58). The underlying value is identical; only the display format differs.

Conversion Performance

Metric	Description	Data type	API Key
All Conversions	Total number of conversion actions attributed to your ads.	Number	`allConversions`
Conversion Goal	Conversion event used to optimize or report conversion performance when available.	Text	Adriel-derived
Conversion Value	The total value of app purchase actions attributed to your ads.	Currency	`total_purchase_value`
Conversions	Total number of conversions attributed to your ads.	Number	`allConversions`
Revenue	The total value of app purchase actions attributed to your ads.	Currency	`total_purchase_value`

TikTok exposes a very broad conversion event set (600+ metrics). Each event surfaces as a count metric with a matching value metric, and Adriel derives KPIs such as ROAS, CPA, and conversion rate from them; the full enumeration is available in the metric picker. Only events active in the ad account are displayed, and custom events may appear under their TikTok-internal IDs unless a friendly label is set in TikTok (TikTok Business API metric descriptions).

Engagement

Metric	Description	Data type	API Key
Engagement	Number of clicks from your ads. This includes clicks that lead to destination as well as those for social and interaction purposes.	Number	`engagements`
Post Comments	Number of comments sent on your ad during the ad impression.	Number	`comments`
Post Engagement	Number of clicks and engagement interactions from your ads.	Number	`engagements`
Post Likes	Number of likes on your ad during the ad impression.	Number	`likes`
Post Reactions	Number of reactions on your ad during the ad impression.	Number	`likes`
Post Saves	Number of saves on the promoted post when TikTok provides it.	Number	Adriel-derived
Post Shares	Number of shares of your ad during the ad impression.	Number	`shares`
Video Impressions	Number of impressions reported for the video ad.	Number	`impressions`

Impression Click Performance

Metric	Description	Data type	API Key
Clicks (All)	Number of clicks reported for the ad.	Number	`clicks`
CPC	Cost per click.	Currency	Adriel-computed
CPM	Cost per thousand impressions.	Currency	Adriel-computed
CTR	Click-through rate — clicks divided by impressions.	Percentage	Adriel-computed
Impressions	Number of times your ads were shown.	Number	`impressions`
Link Clicks	Number of clicks from your ads to a specified destination.	Number	`clicks`
Reach	Number of unique users who saw your ads at least once.	Number	`reach`

Video Performance

Metric	Description	Data type	API Key
2s Video Plays	Number of times your video was played for at least 2 seconds. For each video impression, plays are counted separately and replays are excluded.	Number	`video_watched_2s`
6s Video Plays	Number of times your video was played for at least 6 seconds. For each video impression, plays are counted separately and replays are excluded.	Number	`video_watched_6s`
Video Play	Number of times your video started to play. For each video impression, plays are counted separately and replays are excluded.	Number	`video_play_actions`
Video Played To 100% (Views)	Number of times your video was played 100% of its length. For each impression, views are counted separately and replays are excluded.	Number	`video_views_p100`
Video Played To 25% (Views)	Number of times your video was played at least 25% of its length. For each impression, views are counted separately and replays are excluded.	Number	`video_views_p25`
Video Played To 50% (Views)	Number of times your video was played at least 50% of its length. For each impression, views are counted separately and replays are excluded.	Number	`video_views_p50`
Video Played To 75% (Views)	Number of times your video was played at least 75% of its length. For each impression, views are counted separately and replays are excluded.	Number	`video_views_p75`
Views	Number of times your video started to play. For each video impression, plays are counted separately and replays are excluded.	Number	`video_play_actions`

TikTok-specific

These metrics exist only for TikTok and aren’t part of any cross-connector category. Every group above is a standard category shared with other connectors.

Metric	Description	Data type	API Key
Campaign Budget	Campaign budget reported by TikTok.	Currency	`campaign_budget`
Complete Payment Rate	Percentage of website purchase actions from all clicks attributed to your ads.	Percentage	`complete_payment_rate`
Cost	Cost reported for GMV Max campaign results.	Currency	`cost`
Cost per Complete Payment	Average cost per website purchase action attributed to your ads.	Currency	`cost_per_complete_payment`
Cost per Total Add Payment Info	The average cost per app add payment info action attributed to your ads.	Currency	`cost_total_add_payment_info`
Creative Asset Name	The ad name exactly as it appears on TikTok, before any Smart Ads or ACO preferred name replaces it.	Text	`ad_name`
Creative URL (Expiring)	Original platform image or video URL for the ad creative. This link is time-limited and will expire, unlike the S3-backed Creative URL.	URL	`video.preview_url`, `images.image_url`, `spark.video_info.preview_url`
Credits Spend	The number of unique app spend credit actions attributed to your ads.	Number	`spend_credits`
Gross Revenue	Gross revenue reported for GMV Max campaign results.	Currency	`gross_revenue`
Loan Apply	The number of unique app loan application actions attributed to your ads.	Number	`loan_apply`
Loan Credit	The number of unique app loan approval actions attributed to your ads.	Number	`loan_credit`
Loan Disbursement	The number of unique app loan disbursal actions attributed to your ads.	Number	`loan_disbursement`
Net Cost	Net cost reported for GMV Max campaign results.	Currency	`net_cost`
Orders	Number of SKU orders reported for GMV Max campaign results.	Number	`orders`
Paid Followers	Number of follows to the associated profile during the ad impression.	Number	`follows`
Paid Likes	Number of times your ad was liked during the ad impression.	Number	`likes`
Paid Shares	Number of shares of your ad during the ad impression.	Number	`shares`
Payment Completion Value	Total value of website purchase actions attributed to your ads.	Currency	`total_complete_payment_rate`
Real-Time Cost per App Install	The average cost for each app install event. (The total count is based on when the conversion actually happened.)	Currency	`real_time_app_install_cost`
Tiktok Dark Post Status	Whether the ad is configured as a dark post.	Text	`dark_post_status`
Total Complete Payment Rate	Total value of website purchase actions attributed to your ads.	Number	`total_complete_payment_rate`
Total Engagement	Number of clicks and engagement interactions from your ads.	Number	`engagements`
Total Landing Page Views	Number of landing page view events from your ads.	Number	`total_landing_page_view`
Total Loan Apply	The number of app loan application actions attributed to your ads.	Number	`total_loan_apply`
Total Loan Credit	The number of app loan approval actions attributed to your ads.	Number	`total_loan_credit`
Total Loan Disbursement	The number of app loan disbursal actions attributed to your ads.	Number	`total_loan_disbursement`
Total Spend Credits	The number of app spend credit actions attributed to your ads.	Number	`total_spend_credits`
Value per Complete Payment	Average value per website purchase action attributed to your ads.	Currency	`value_per_complete_payment`
Video Average Play Time	Average time your video was played per single video view, including any time spent replaying the video.	Duration	`average_video_play`

Breakdowns

Basic

Breakdown	Description	API Key
Channel	Groups results by advertising channel.	Adriel-assigned

Campaign Structure

Breakdown	Description	API Key
Ad	Groups results by TikTok ad.	Adriel-derived
Ad Account	Groups results by TikTok ad account.	Adriel-derived
Ad Name	Groups results by ad name.	Adriel-derived
Ad Set	Groups results by TikTok ad group.	Adriel-derived
Ad Set Name	Groups results by ad group name.	Adriel-derived
Campaign	Groups results by TikTok campaign.	Adriel-derived
Campaign Name	Groups results by campaign name.	Adriel-derived
Objective	The advertising objective selected for the campaign, ad group, or ad.	`objective_type`
Platform	Groups results by normalized TikTok subchannel classification.	Adriel-derived
Status	The current delivery and review status of the selected campaign, ad group, or ad.	`operation_status`, `secondary_status`

Creatives

Adriel post-processes ad creatives to generate these breakdowns.

Breakdown	Description	API Key
Ad Copy	Groups results by words identified in the ad creative.	Adriel-derived
Color Clustering	Groups results by similar colors identified in the ad creative.	Adriel-derived
Creative Image	Unique visual identifier used to group identical or near-identical creatives.	Adriel-derived
Emoji Analysis	Groups results by emojis identified in the ad creative.	Adriel-derived

Date

TikTok reports daily performance records; all time-grouping breakdowns are Adriel-side aggregations of the same underlying daily data.

Breakdown	Description	API Key
Auto Time Breakdown	Automatically groups results by an appropriate time interval for the selected date range.	Adriel-side
Daily Breakdown	Groups results by calendar day.	Adriel-side
Hourly Breakdown	Groups results by the hour of day in the report timezone.	`stat_time_hour`
Monthly Breakdown	Groups results by calendar month.	Adriel-side
Quarterly Breakdown	Groups results by calendar quarter.	Adriel-side
Week Date Breakdown	Groups results by the date representing each reporting week.	Adriel-side
Week Number Breakdown (W#)	Groups results by week number in the year.	Adriel-side
Weekly Breakdown (Start: Mon)	Groups results by calendar week.	Adriel-side
Weekly Breakdown (Start: Sun)	Groups results into weeks running from Sunday through Saturday.	Adriel-side
Yearly Breakdown	Groups results by calendar year.	Adriel-side

Others

Breakdown	Description	API Key
No Grouping	Shows all results as a single combined group.	Adriel-side

TikTok-specific

These breakdowns exist only for TikTok and aren’t part of any cross-connector category. Every group above is a standard category shared with other connectors.

Breakdown	Description	API Key
Age	Groups results by TikTok-reported age range.	`age`
Country	Groups results by the country code reported by TikTok.	`country_code`
Creative Description	Groups results by the ad description text.	`ad_text`, `ad_texts`
Creative Headline	Groups results by the ad headline or display title.	`display_name`
DMA Region	Groups results by DMA region when TikTok reports a DMA identifier.	`dma_id`
Gender	Groups results by TikTok-reported gender.	`gender`
Location	Groups results by the province or region reported by TikTok.	`province_id`
Operating System	Groups results by the device operating system reported by TikTok.	`platform`
Placement	Groups results by TikTok placement.	`placement`
State (US Only)	Groups results by U.S. state when TikTok location data can be mapped to a state.	Adriel-derived

Limitations

Cache-only report data — dashboard queries read from the last cached snapshot rather than live from TikTok; data outside the cache sync period may be incomplete or inaccurate.
No current-day data — the TikTok API does not provide data for the current calendar day (TikTok Marketing API — Reporting).
Per-ad-account breakdown scope — gender, age, location, platform placement, OS, and country breakdowns are computed per ad account.
Uniqueness overcounting — reach and other uniqueness-based metrics can be overvalued over date ranges longer than one day, because uniqueness is computed per snapshot.
Massive metric set — with 600+ conversion-related metrics, the picker can feel overwhelming; starting with standard ROAS and conversion metrics before drilling into specific event types is the usual approach.
Window-specific ROAS — Day0, Day2, and Day6 variants represent different attribution windows and are not directly comparable within the same widget.
Custom Pixel events — custom events configured in TikTok Ads Manager may surface under their TikTok-internal IDs unless a friendly label has been set in TikTok.
Token expiry — OAuth tokens occasionally expire and require re-authorization from the connections list.

API references

TikTok Marketing API — connector uses Marketing API v1.3 (base URL https://business-api.tiktok.com/open_api/v1.3/)
Reporting (Basic and Audience)
Metrics reference
Authorization (OAuth 2.0)

​Introduction

​Data refresh strategy

​Architecture data

​Reports data

​Architecture levels

​Date range limits

​Metrics

​Basic

​Campaign Attributes

​Campaign Structure

​Computed Metric

​Conversion Performance

​Engagement

​Impression Click Performance

​Video Performance

​TikTok-specific

​Breakdowns

​Basic

​Campaign Structure

​Creatives

​Date

​Others

​TikTok-specific

​Limitations

​API references

​See also

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Metrics

Basic

Campaign Attributes

Campaign Structure

Computed Metric

Conversion Performance

Engagement

Impression Click Performance

Video Performance

TikTok-specific

Breakdowns

Basic

Campaign Structure

Creatives

Date

Others

TikTok-specific

Limitations

API references

See also