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 columns Data type uses this 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 name. Italic text describes how a value is produced when it doesn’t map cleanly to a single API field.

Performance

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.

Metric	Description	Data type	API Key
Impressions	Total times the ads were shown, regardless of interaction.	Number	`impressions`
Gross impressions	Impressions before fraud filtering.	Number	`gross_impressions`
Reach	Unique users who saw the ad at least once.	Number	`reach`
Frequency	Average impressions per reached user.	Ratio	`frequency`
Clicks (all)	Total clicks, including link, social, and carousel interactions.	Number	`clicks`
Link clicks	Clicks on the ad’s link or CTA.	Number	`clicks`
CTR	Click-through rate.	Percentage	`ctr`
CPM	Cost per thousand impressions.	Currency	`cpm`
CPC	Cost per click.	Currency	`cpc`
Ad spend	Total amount spent.	Currency	`spend`
Conversions	Attributed actions matching the defined conversion events. Defaults to purchase when no event is set.	Number	`allConversions`
Conversion value	Monetary value of attributed conversions.	Currency	`total_purchase_value`
Revenue	Monetary value of attributed conversions.	Currency	`total_purchase_value`

Engagement

Metric	Description	Data type	API Key
Engagement	All engagement actions.	Number	`engagements`
Likes	Likes on the ad.	Number	`likes`
Comments	Comments on the ad.	Number	`comments`
Shares	Shares of the ad.	Number	`shares`
Follows	New follows attributed to the ad.	Number	`follows`
Profile visits	Profile visits attributed to the ad.	Number	`profile_visits`
Paid engaged view	Engaged views, as defined by TikTok.	Number	`paid_engaged_view`
Engaged view 15s	Views of at least 15 seconds.	Number	`engaged_view_15s`

Video performance

Metric	Description	Data type	API Key
Views	Aggregated count of all qualified video views.	Number	`video_play_actions`
Video play actions	Total video plays.	Number	`video_play_actions`
Real-time video plays	Real-time play count, as opposed to attributed.	Number	`real_time_video_play_actions`
2s video plays	Views where the video played for at least two seconds.	Number	`video_watched_2s`
6s video plays	Views where the video played for at least six seconds.	Number	`video_watched_6s`
Video played to 25% / 50% / 75% / 100% (Views)	Plays reaching each completion threshold.	Number	`video_views_p25` / `_p50` / `_p75` / `_p100`
Average video play	Average time watched.	Duration	`average_video_play`

Conversion events

TikTok exposes a very broad conversion event set — 600+ metrics in total. Each event has a count metric and a corresponding : Conversion value metric (Currency, for example purchase_value or total_purchase_value). The categories below cover the most common groupings; the full enumeration is available in the metric picker. E-commerce events — purchase, complete_payment, total_purchase, add_to_wishlist, app_event_add_to_cart, web_event_add_to_cart, checkout, initiate_checkout, add_billing, add_payment_info, total_pageview, page_browse_view, view_content, total_view_content, product_details_page_browse, onsite_total_purchase, onsite_total_add_to_cart, onsite_total_checkout_initiation App events — app_install, download_start, evta_app_install, real_time_app_install, cta_app_install, total_app_event_add_to_cart, launch_app, total_launch_app, next_day_open, day7_retention Lead and sign-up events — form, onsite_form, registration, total_registration, user_registration, total_sales_lead, subscribe, total_subscribe, start_trial, total_start_trial Engagement events — button_click, anchor_clicks, clicks_on_hashtag_challenge, clicks_on_music_disc, duet_clicks, stitch_clicks, tt_playlist_visit Game events — achieve_level, total_achieve_level, complete_tutorial, total_complete_tutorial, unlock_achievement, total_unlock_achievement, create_gamerole, total_create_gamerole, join_group, total_join_group

ROAS

TikTok reports ROAS and its underlying purchase value across three attribution windows: Day0, Day2, and Day6. These are separate metric variants and are not directly comparable within the same widget.

Metric	Description	Data type	API Key
Total Purchase ROAS Day0	ROAS for purchases attributed within day 0.	Ratio	`total_purchase_roas_day0`
Total Purchase ROAS Day2	ROAS within a 2-day window.	Ratio	`total_purchase_roas_day2`
Total Purchase ROAS Day6	ROAS within a 6-day window.	Ratio	`total_purchase_roas_day6`
Total Purchase value Day0 / Day2 / Day6	Purchase value for each window.	Currency	`total_purchase_value_day0` / `_day2` / `_day6`
Ad impression ad revenue ROAS Day0 / Day2 / Day6	Revenue ROAS across windows.	Ratio	`ad_impression_ad_revenue_roas_day0` / `_day2` / `_day6`

View-through and engaged view-through

TikTok separates view-through (vta_*) and engaged view-through (evta_*) attribution. The standard event metrics cover most reporting needs; these variants are useful when comparing attribution paths. Each variant also carries a matching : Conversion value metric.

Metric	Description	Data type	API Key
View-through attributed actions	View-through attributed conversions, such as purchase, registration, or app install.	Number	`vta_purchase`, `vta_registration`, `vta_app_install`, `vta_complete_payment`, `vta_conversion`
Engaged view-through attributed actions	Engaged view-through attributed conversions.	Number	`evta_app_install`, `evta_purchase`, `evta_payments_completed`, `evta_registration`

Campaign structure metadata

Metric	Description	Data type	API Key
Ad account name	Name of the TikTok ad account.	Text	Resolved from TikTok account ID
Campaign name	Campaign name.	Text	`campaign_name`
Ad set name	Ad set name. TikTok uses adgroup terminology internally.	Text	`adgroup_name`
Ad name	Ad name.	Text	`ad_name`
Currency	Reporting currency.	Text	`currency`
Daily budget	Daily budget set on the campaign or ad set.	Currency	`budget`
Bid strategy	Bid strategy set on the ad set or campaign.	Text	Derived from `deliveryMethod` and `bid_type`
Bid cap	Bid cap set on the ad set or campaign.	Currency	`bid_price`
Creative URL	Preview URL for the ad creative.	URL	Resolved from creative metadata
Starts	Schedule start date.	Date	`schedule_start_time`
Ends	Schedule end date.	Date	`schedule_end_time`
Created at	Creation date.	Date	`create_time`

Breakdowns

Campaign structure

Breakdown	Description	API Key
Ad account	Group by ad account.	`name`
Campaign	Group by campaign.	`campaign_name`
Ad set	Group by ad set.	`adgroup_name`
Ad	Group by ad.	`ad_name`

Audience

Breakdown	Description	API Key
Age	Audience age bracket (per ad account).	`age`
Gender	Audience gender (per ad account).	`gender`

Geography

Breakdown	Description	API Key
Country	Country (per ad account).	`country_code`
Location	Geographic region; can be cities or regions depending on the platform (per ad account).	`province_id`
DMA region	Designated market area.	`dma_id`

Delivery and placement

Breakdown	Description	API Key
Platform placement	TikTok placement (per ad account).	`placement_id`
OS	Operating system on which the impression was served (per ad account).	`platform`
Objective	Group campaigns by their objective.	`objective_type`
Status	Group by delivery status.	`operation_status`, `secondary_status`

Time

Breakdown	Description	API Key
Hourly breakdown	Group results by the hour of the impression, for example 20:00:00 – 20:59:59. Hours are aggregated across days when the range spans multiple days.	`stat_time_hour`

Channel

Channel is an Adriel-provided constant grouping label, always “tiktok”, used for cross-connector rollup.

Breakdown	Description
Channel	Constant grouping label for cross-connector rollup.

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

​Performance

​Engagement

​Video performance

​Conversion events

​ROAS

​View-through and engaged view-through

​Campaign structure metadata

​Breakdowns

​Campaign structure

​Audience

​Geography

​Delivery and placement

​Time

​Channel

​Limitations

​API references

​See also

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Metrics

Performance

Engagement

Video performance

Conversion events

ROAS

View-through and engaged view-through

Campaign structure metadata

Breakdowns

Campaign structure

Audience

Geography

Delivery and placement

Time

Channel

Limitations

API references

See also