> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Data reference
> Metrics, breakdowns, refresh cadence, and limits for the TikTok Ads data source in Adriel.
## 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-sources/o-z/tiktok/how-to-connect).
## 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](https://business-api.tiktok.com/portal/docs?id=1738864915188737)).
* **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](https://business-api.tiktok.com/portal/docs) — connector uses Marketing API v1.3 (base URL `https://business-api.tiktok.com/open_api/v1.3/`)
* [Reporting (Basic and Audience)](https://business-api.tiktok.com/portal/docs?id=1738864915188737)
* [Metrics reference](https://business-api.tiktok.com/portal/docs?id=1751443967255553)
* [Authorization (OAuth 2.0)](https://business-api.tiktok.com/portal/docs?id=1738373141733378)
## See also
* [How to connect TikTok Ads to Adriel](/data-sources/o-z/tiktok/how-to-connect) (paired how-to)
* [Meta Ads data reference](/data-sources/g-n/meta-ads/data-reference) — for paid social attribution comparison