> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# TikTok Ads as a data source
> Bring data from TikTok Ads to Nekt.
TikTok Ads is TikTok's advertising platform that enables businesses to create and manage video-based advertising campaigns on one of the world's fastest-growing social media platforms. It provides tools for targeting audiences, tracking performance, and optimizing ad spend to reach over 1 billion active users worldwide.
## Configuring TikTok Ads as a Source
In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the TikTok Ads option from the list of connectors.
Click **Next** and you'll be prompted to add your access.
### 1. Add account access
You'll need to authorize Nekt to access your TikTok Ads data. Click on the `TikTok Authorization` button and log in with your TikTok account. Grant the necessary permissions for the ad accounts you want to extract data from.
The following configurations are available:
* **Advertiser Account ID**: The unique identifier for your TikTok Ads account. You can find this in the TikTok Ads Manager by clicking on your account name in the top-right corner. For detailed instructions, see [TikTok's guide on finding your Ad Account ID](https://ads.tiktok.com/help/article/find-your-ad-account-id?lang=en).
* **Start Date**: The earliest date from which records will be synced. This should be in YYYY-MM-DD format.
* **Lookback Window**: (Default: 7 days) The number of days to refetch data from the current date. This helps ensure data accuracy as TikTok may update conversion data retroactively.
* **Include Deleted**: (Default: `true`) When enabled, deleted ads, ad groups, and campaigns will also be extracted. This is useful for historical analysis and auditing.
Once you're done, click **Next**.
### 2. Select streams
Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.
> Tip: The stream can be found more easily by typing its name.
Select the streams and click **Next**.
### 3. Configure data streams
Customize how you want your data to appear in your catalog. Select a name for each table (which will contain the fetched data) and the type of sync.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** and make this process faster!
* **Sync Type**: you can choose between INCREMENTAL and FULL\_TABLE.
* Incremental: every time the extraction happens, we'll get only the new data - which is good if, for example, you want to keep every record ever fetched.
* Full table: every time the extraction happens, we'll get the current state of the data - which is good if, for example, you don't want to have deleted data in your catalog.
Once you are done configuring, click **Next**.
### 4. Configure data source
Describe your data source for easy identification within your organization, not exceeding 140 characters.
To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).
Optionally, you can determine when to execute a [full sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync). This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.
Once you are ready, click **Next** to finalize the setup.
### 5. Check your new source
You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.
# Streams and Fields
Below you'll find all available data streams from TikTok Ads and their corresponding fields:
Stream containing information about your TikTok advertiser accounts.
**Key Fields:**
* `advertiser_id` - Unique identifier for the advertiser account
* `name` - Name of the advertiser account
* `company` - Company name
* `balance` - Account balance
* `currency` - Account currency
* `timezone` - Account timezone
* `display_timezone` - Display timezone setting
* `status` - Account status
* `role` - User role in the account
**Contact Information:**
* `email` - Contact email
* `telephone` - Contact telephone
* `phonenumber` - Contact phone number
* `contacter` - Contact person name
* `address` - Business address
* `country` - Country
**Business Details:**
* `industry` - Industry category
* `brand` - Brand name
* `description` - Account description
* `promotion_area` - Promotion area
* `promotion_center_city` - Promotion center city
* `promotion_center_province` - Promotion center province
* `create_time` - Account creation timestamp
* `language` - Account language
* `owner_bc_id` - Owner business center ID
**License Information:**
* `license_no` - License number
* `license_url` - License URL
* `license_city` - License city
* `license_province` - License province
Stream for managing ad campaigns and their settings.
**Key Fields:**
* `campaign_id` - Unique identifier for the campaign
* `campaign_name` - Name of the campaign
* `advertiser_id` - ID of the advertiser account
* `objective_type` - Campaign objective type
* `operation_status` - Operational status (e.g., ENABLE, DISABLE)
* `secondary_status` - Secondary status details
* `create_time` - Campaign creation time
* `modify_time` - Last modification time
**Campaign Settings:**
* `campaign_type` - Type of campaign
* `campaign_system_origin` - System origin of the campaign
* `is_search_campaign` - Whether it's a search campaign
* `is_smart_performance_campaign` - Whether smart performance is enabled
* `is_advanced_dedicated_campaign` - Whether advanced dedicated campaign
* `is_new_structure` - Whether using new structure
**Budget & Bidding:**
* `budget` - Campaign budget
* `budget_mode` - Budget mode (BUDGET\_MODE\_DAY, BUDGET\_MODE\_TOTAL)
* `budget_optimize_on` - Budget optimization setting
* `bid_type` - Bid type
* `deep_bid_type` - Deep bid type
* `roas_bid` - ROAS bid value
* `optimization_goal` - Optimization goal
**App Promotion:**
* `app_id` - Associated app ID
* `app_promotion_type` - App promotion type
* `campaign_app_profile_page_state` - App profile page state
* `campaign_product_source` - Product source
**Advanced Settings:**
* `special_industries` - Array of special industry categories
* `rf_campaign_type` - Reach & Frequency campaign type
* `rta_id` - RTA ID
* `rta_product_selection_enabled` - RTA product selection status
* `postback_window_mode` - Postback window mode
* `objective` - Campaign objective
Stream for managing ad groups within campaigns, controlling targeting, budget, and scheduling.
**Key Fields:**
* `adgroup_id` - Unique identifier for the ad group
* `adgroup_name` - Name of the ad group
* `campaign_id` - Parent campaign ID
* `campaign_name` - Parent campaign name
* `advertiser_id` - Advertiser account ID
* `operation_status` - Operational status
* `secondary_status` - Secondary status details
* `create_time` - Creation time
* `modify_time` - Last modification time
**Targeting:**
* `location_ids` - Targeted location IDs
* `zipcode_ids` - Targeted zipcode IDs
* `languages` - Targeted languages
* `gender` - Targeted gender
* `age_groups` - Targeted age groups
* `spending_power` - Spending power targeting
* `household_income` - Household income targeting
* `audience_ids` - Custom audience IDs
* `excluded_audience_ids` - Excluded audience IDs
* `interest_category_ids` - Interest category IDs
* `interest_keyword_ids` - Interest keyword IDs
* `purchase_intention_keyword_ids` - Purchase intention keyword IDs
**Budget & Bidding:**
* `budget` - Ad group budget
* `budget_mode` - Budget mode
* `scheduled_budget` - Scheduled budget
* `bid_type` - Bid type
* `bid_price` - Bid price
* `conversion_bid_price` - Conversion bid price
* `deep_bid_type` - Deep bid type
* `deep_cpa_bid` - Deep CPA bid
* `roas_bid` - ROAS bid
**Scheduling:**
* `schedule_type` - Schedule type
* `schedule_start_time` - Schedule start time
* `schedule_end_time` - Schedule end time
* `dayparting` - Dayparting schedule
**Placement & Delivery:**
* `placement_type` - Placement type
* `placements` - Array of placements
* `optimization_goal` - Optimization goal
* `optimization_event` - Optimization event
* `billing_event` - Billing event
* `pacing` - Pacing setting
* `delivery_mode` - Delivery mode
**Device Targeting:**
* `operating_systems` - Targeted operating systems
* `min_android_version` - Minimum Android version
* `min_ios_version` - Minimum iOS version
* `ios14_targeting` - iOS 14+ targeting setting
* `device_model_ids` - Targeted device models
* `network_types` - Targeted network types
* `carrier_ids` - Targeted carrier IDs
**Attribution:**
* `click_attribution_window` - Click attribution window
* `view_attribution_window` - View attribution window
* `engaged_view_attribution_window` - Engaged view attribution window
**Shopping Ads:**
* `shopping_ads_type` - Shopping ads type
* `shopping_ads_retargeting_type` - Retargeting type
* `store_id` - Store ID
* `catalog_id` - Catalog ID
Stream for managing individual ads within an ad group.
**Key Fields:**
* `ad_id` - Unique identifier for the ad
* `ad_name` - Name of the ad
* `adgroup_id` - Parent ad group ID
* `adgroup_name` - Parent ad group name
* `campaign_id` - Parent campaign ID
* `campaign_name` - Parent campaign name
* `advertiser_id` - Advertiser account ID
* `operation_status` - Operational status
* `secondary_status` - Secondary status details
* `create_time` - Creation time
* `modify_time` - Last modification time
**Creative Content:**
* `ad_text` - Primary ad text
* `ad_texts` - Additional ad texts
* `ad_format` - Ad format type
* `video_id` - Video asset ID
* `image_ids` - Image asset IDs
* `music_id` - Music asset ID
* `carousel_image_index` - Carousel image index
* `tiktok_item_id` - TikTok item ID
* `creative_type` - Creative type
**Call to Action:**
* `call_to_action` - Call to action text
* `call_to_action_id` - Call to action ID
* `card_id` - Card ID
**Landing & Destination:**
* `landing_page_url` - Landing page URL
* `deeplink` - Deep link URL
* `deeplink_type` - Deep link type
* `cpp_url` - CPP URL
* `page_id` - Page ID
* `dynamic_destination` - Dynamic destination setting
**Tracking:**
* `tracking_pixel_id` - Pixel ID for tracking
* `tracking_app_id` - App ID for tracking
* `tracking_offline_event_set_ids` - Offline event set IDs
* `impression_tracking_url` - Impression tracking URL
* `click_tracking_url` - Click tracking URL
* `utm_params` - UTM parameters array
**Identity:**
* `identity_id` - Identity ID
* `identity_type` - Identity type
* `display_name` - Display name
* `profile_image_url` - Profile image URL
* `avatar_icon_web_uri` - Avatar icon URI
**Shopping:**
* `catalog_id` - Catalog ID
* `product_set_id` - Product set ID
* `sku_ids` - SKU IDs
* `item_group_ids` - Item group IDs
* `showcase_products` - Showcase products array
**Brand Safety:**
* `vast_moat_enabled` - VAST MOAT enabled
* `viewability_postbid_partner` - Viewability partner
* `brand_safety_postbid_partner` - Brand safety partner
Daily performance metrics for ads (Auction buying type).
**Dimensions:**
* `ad_id` - Ad identifier
* `stat_time_day` - Date of the metrics
**Basic Metrics:**
* `spend` - Total ad spend
* `billed_cost` - Billed cost (excluding credits/coupons)
* `impressions` - Number of ad impressions
* `gross_impressions` - Total impressions including invalid
* `clicks` - Number of clicks
* `ctr` - Click-through rate
* `cpc` - Cost per click
* `cpm` - Cost per 1,000 impressions
* `reach` - Unique users reached
* `cost_per_1000_reached` - Cost to reach 1,000 users
* `frequency` - Average impressions per user
**Conversion Metrics:**
* `conversion` - Number of conversions
* `cost_per_conversion` - Cost per conversion
* `conversion_rate_v2` - Conversion rate
* `real_time_conversion` - Real-time conversions
* `real_time_cost_per_conversion` - Real-time CPA
* `real_time_conversion_rate_v2` - Real-time conversion rate
**Result Metrics:**
* `result` - Number of results based on objective
* `cost_per_result` - Cost per result
* `result_rate` - Result rate
* `real_time_result` - Real-time results
* `real_time_cost_per_result` - Real-time cost per result
* `secondary_goal_result` - Secondary goal results
* `cost_per_secondary_goal_result` - Cost per secondary result
**Video Metrics:**
* `video_play_actions` - Video play count
* `video_watched_2s` - 2-second video views
* `video_watched_6s` - 6-second video views
* `engaged_view` - Engaged views (6s or interaction)
* `engaged_view_15s` - 15-second engaged views
* `video_views_p25` - 25% video completion views
* `video_views_p50` - 50% video completion views
* `video_views_p75` - 75% video completion views
* `video_views_p100` - 100% video completion views
* `average_video_play` - Average video play time
* `average_video_play_per_user` - Average play time per user
**SKAN Metrics (iOS):**
* `skan_result` - SKAdNetwork results
* `skan_cost_per_result` - SKAN cost per result
* `skan_conversion` - SKAN conversions
* `skan_cost_per_conversion` - SKAN cost per conversion
Hourly performance metrics for ads (Auction buying type).
**Dimensions:**
* `ad_id` - Ad identifier
* `stat_time_hour` - Hour of the metrics
Includes all basic and video metrics from the Daily Report (excluding SKAN metrics).
Daily performance metrics for ads in Reservation campaigns (TopView and Reach & Frequency).
**Dimensions:**
* `ad_id` - Ad identifier
* `stat_time_day` - Date of the metrics
**Buying Types:** RESERVATION\_TOP\_VIEW, RESERVATION\_RF
Same metrics as the Ads Daily Report (basic, conversion, result, video, and SKAN metrics).
Hourly performance metrics for ads in Reservation campaigns (TopView and Reach & Frequency).
**Dimensions:**
* `ad_id` - Ad identifier
* `stat_time_hour` - Hour of the metrics
**Buying Types:** RESERVATION\_TOP\_VIEW, RESERVATION\_RF
Same metrics as the Ads Hourly Report (basic and video metrics, excluding SKAN).
Daily performance metrics broken down by audience demographics.
**Dimensions:**
* `ad_id` - Ad identifier
* `stat_time_day` - Date of the metrics
* `age` - Age group (e.g., AGE\_18\_24, AGE\_25\_34)
* `gender` - Gender (MALE, FEMALE)
**Basic Metrics:**
* `spend` - Total spend
* `impressions` - Impressions
* `gross_impressions` - Gross impressions
* `clicks` - Clicks
* `ctr` - Click-through rate
* `cpc` - Cost per click
* `cpm` - Cost per mille
**Conversion Metrics:**
* `conversion` - Conversions
* `cost_per_conversion` - CPA
* `conversion_rate` - CVR
* `real_time_conversion` - Real-time conversions
* `real_time_cost_per_conversion` - Real-time CPA
* `real_time_conversion_rate` - Real-time CVR
**Result Metrics:**
* `result` - Results
* `cost_per_result` - Cost per result
* `result_rate` - Result rate
* `real_time_result` - Real-time results
* `real_time_cost_per_result` - Real-time cost per result
* `real_time_result_rate` - Real-time result rate
Daily performance metrics broken down by country.
**Dimensions:**
* `ad_id` - Ad identifier
* `stat_time_day` - Date of the metrics
* `country_code` - Country code (ISO 2-letter)
Same metrics as the Age & Gender Report.
Daily performance metrics broken down by user language.
**Dimensions:**
* `ad_id` - Ad identifier
* `stat_time_day` - Date of the metrics
* `language` - User language code
Same metrics as the Age & Gender Report.
Daily performance metrics broken down by platform/device.
**Dimensions:**
* `ad_id` - Ad identifier
* `stat_time_day` - Date of the metrics
* `platform` - Platform (ANDROID, IOS)
Same metrics as the Age & Gender Report.
Web/landing page conversion event metrics for ads.
**Dimensions:**
* `ad_id` - Ad identifier
* `stat_time_day` - Date of the metrics
**Payment Metrics:**
* `complete_payment` - Complete payment events
* `cost_per_complete_payment` - Cost per payment
* `complete_payment_rate` - Payment rate
* `value_per_complete_payment` - Value per payment
* `complete_payment_roas` - Payment ROAS
**Registration Metrics:**
* `user_registration` - Registration events
* `cost_per_user_registration` - Cost per registration
* `user_registration_rate` - Registration rate
* `value_per_user_registration` - Value per registration
**Product View Metrics:**
* `product_details_page_browse` - Product page views
* `cost_per_product_details_page_browse` - Cost per view
* `product_details_page_browse_rate` - View rate
**Cart Metrics:**
* `web_event_add_to_cart` - Add to cart events
* `cost_per_web_event_add_to_cart` - Cost per add to cart
* `web_event_add_to_cart_rate` - Add to cart rate
**Checkout Metrics:**
* `initiate_checkout` - Checkout initiations
* `cost_per_initiate_checkout` - Cost per checkout
* `initiate_checkout_rate` - Checkout rate
**Wishlist Metrics:**
* `on_web_add_to_wishlist` - Add to wishlist events
* `cost_per_on_web_add_to_wishlist` - Cost per wishlist add
Mobile app conversion event metrics for ads (Auction buying type).
**Dimensions:**
* `ad_id` - Ad identifier
* `stat_time_day` - Date of the metrics
**Purchase Metrics:**
* `purchase` - In-app purchases
* `cost_per_purchase` - Cost per purchase
* `purchase_rate` - Purchase rate
* `total_purchase` - Total purchases
* `total_purchase_value` - Total purchase value
* `total_active_pay_roas` - Purchase ROAS
**Checkout Metrics:**
* `checkout` - App checkout events
* `cost_per_checkout` - Cost per checkout
* `checkout_rate` - Checkout rate
* `total_checkout_value` - Total checkout value
**View Content Metrics:**
* `view_content` - View content events
* `cost_per_view_content` - Cost per view
* `view_content_rate` - View rate
**Cart Metrics:**
* `app_event_add_to_cart` - App add to cart
* `cost_per_app_event_add_to_cart` - Cost per add to cart
* `app_event_add_to_cart_rate` - Add to cart rate
**Wishlist Metrics:**
* `add_to_wishlist` - Add to wishlist events
* `cost_per_add_to_wishlist` - Cost per wishlist add
* `add_to_wishlist_rate` - Wishlist rate
Web/landing page conversion event metrics for ads in Reservation campaigns.
**Dimensions:**
* `ad_id` - Ad identifier
* `stat_time_day` - Date of the metrics
**Buying Types:** RESERVATION\_TOP\_VIEW, RESERVATION\_RF
Same metrics as Ads Page Event Daily Report.
Mobile app conversion event metrics for ads in Reservation campaigns.
**Dimensions:**
* `ad_id` - Ad identifier
* `stat_time_day` - Date of the metrics
**Buying Types:** RESERVATION\_TOP\_VIEW, RESERVATION\_RF
Same metrics as Ads In-App Event Daily Report.
Daily performance metrics at the ad group level (Auction buying type).
**Dimensions:**
* `adgroup_id` - Ad group identifier
* `stat_time_day` - Date of the metrics
Same metrics as the Ads Daily Report (basic, conversion, result, video, and SKAN metrics).
Hourly performance metrics at the ad group level (Auction buying type).
**Dimensions:**
* `adgroup_id` - Ad group identifier
* `stat_time_hour` - Hour of the metrics
Same metrics as the Ads Hourly Report (basic and video metrics, excluding SKAN).
Daily performance metrics at the ad group level for Reservation campaigns.
**Dimensions:**
* `adgroup_id` - Ad group identifier
* `stat_time_day` - Date of the metrics
**Buying Types:** RESERVATION\_TOP\_VIEW, RESERVATION\_RF
Same metrics as the Ads Daily Report.
Hourly performance metrics at the ad group level for Reservation campaigns.
**Dimensions:**
* `adgroup_id` - Ad group identifier
* `stat_time_hour` - Hour of the metrics
**Buying Types:** RESERVATION\_TOP\_VIEW, RESERVATION\_RF
Same metrics as the Ads Hourly Report.
Daily performance metrics at the campaign level (Auction buying type).
**Dimensions:**
* `campaign_id` - Campaign identifier
* `stat_time_day` - Date of the metrics
Same metrics as the Ads Daily Report (basic, conversion, result, video, and SKAN metrics).
Hourly performance metrics at the campaign level (Auction buying type).
**Dimensions:**
* `campaign_id` - Campaign identifier
* `stat_time_hour` - Hour of the metrics
Same metrics as the Ads Hourly Report (basic and video metrics, excluding SKAN).
Daily performance metrics at the campaign level for Reservation campaigns.
**Dimensions:**
* `campaign_id` - Campaign identifier
* `stat_time_day` - Date of the metrics
**Buying Types:** RESERVATION\_TOP\_VIEW, RESERVATION\_RF
Same metrics as the Ads Daily Report.
Hourly performance metrics at the campaign level for Reservation campaigns.
**Dimensions:**
* `campaign_id` - Campaign identifier
* `stat_time_hour` - Hour of the metrics
**Buying Types:** RESERVATION\_TOP\_VIEW, RESERVATION\_RF
Same metrics as the Ads Hourly Report.
Daily performance metrics at the campaign level broken down by demographics.
**Dimensions:**
* `campaign_id` - Campaign identifier
* `stat_time_day` - Date of the metrics
* `age` - Age group (e.g., AGE\_18\_24, AGE\_25\_34)
* `gender` - Gender (MALE, FEMALE)
Same audience metrics as Ads Age & Gender Report (spend, impressions, clicks, ctr, cpc, cpm, conversion, cost\_per\_conversion, conversion\_rate, result, cost\_per\_result, result\_rate, and real-time variants).
Daily performance metrics at the campaign level broken down by country.
**Dimensions:**
* `campaign_id` - Campaign identifier
* `stat_time_day` - Date of the metrics
* `country_code` - Country code (ISO 2-letter)
Same audience metrics as Ads Country Report.
Daily performance metrics at the campaign level broken down by user language.
**Dimensions:**
* `campaign_id` - Campaign identifier
* `stat_time_day` - Date of the metrics
* `language` - User language code
Same audience metrics as Ads Language Report.
Daily performance metrics at the campaign level broken down by platform/device.
**Dimensions:**
* `campaign_id` - Campaign identifier
* `stat_time_day` - Date of the metrics
* `platform` - Platform (ANDROID, IOS)
Same audience metrics as Ads Platform Report.
Web/landing page conversion event metrics at the campaign level (Auction buying type).
**Dimensions:**
* `campaign_id` - Campaign identifier
* `stat_time_day` - Date of the metrics
Same metrics as Ads Page Event Daily Report (payment, registration, product view, cart, checkout, and wishlist metrics).
Web/landing page conversion event metrics at the campaign level for Reservation campaigns.
**Dimensions:**
* `campaign_id` - Campaign identifier
* `stat_time_day` - Date of the metrics
**Buying Types:** RESERVATION\_TOP\_VIEW, RESERVATION\_RF
Same metrics as Ads Page Event Daily Report.
Mobile app conversion event metrics at the campaign level (Auction buying type).
**Dimensions:**
* `campaign_id` - Campaign identifier
* `stat_time_day` - Date of the metrics
Same metrics as Ads In-App Event Daily Report (purchase, checkout, view content, cart, and wishlist metrics).
Mobile app conversion event metrics at the campaign level for Reservation campaigns.
**Dimensions:**
* `campaign_id` - Campaign identifier
* `stat_time_day` - Date of the metrics
**Buying Types:** RESERVATION\_TOP\_VIEW, RESERVATION\_RF
Same metrics as Ads In-App Event Daily Report.
# Data Model
The following diagram illustrates the relationships between the core data streams in TikTok Ads. The arrows indicate the join keys that link the different entities.
```mermaid theme={null}
graph TD;
subgraph "Core Entities"
AdAccounts("Ad Accounts");
Campaigns("Campaigns");
AdGroups("Ad Groups");
Ads("Ads");
end
subgraph "Performance Reports"
AdsDailyReport("Ads Daily Report");
AdsHourlyReport("Ads Hourly Report");
AdGroupsReport("Ad Groups Reports");
CampaignsReport("Campaigns Reports");
end
subgraph "Audience Breakdowns"
AgeGender("Age & Gender Report");
Country("Country Report");
Platform("Platform Report");
Language("Language Report");
end
subgraph "Event Reports"
PageEvents("Page Event Reports");
InAppEvents("In-App Event Reports");
end
Campaigns -- "advertiser_id" --> AdAccounts;
AdGroups -- "campaign_id" --> Campaigns;
Ads -- "adgroup_id" --> AdGroups;
Ads -- "campaign_id" --> Campaigns;
AdsDailyReport -- "ad_id" --> Ads;
AdsHourlyReport -- "ad_id" --> Ads;
AdGroupsReport -- "adgroup_id" --> AdGroups;
CampaignsReport -- "campaign_id" --> Campaigns;
AgeGender -- "ad_id" --> Ads;
Country -- "ad_id" --> Ads;
Platform -- "ad_id" --> Ads;
Language -- "ad_id" --> Ads;
PageEvents -- "ad_id" --> Ads;
InAppEvents -- "ad_id" --> Ads;
```
# Use Cases for Data Analysis
This guide outlines valuable business intelligence use cases when consolidating TikTok Ads data, along with ready-to-use SQL queries that you can run on [Explorer](https://app.nekt.ai/explorer).
## Campaign Performance Analysis
### 1. Campaign Performance Overview
Track the overall performance of your campaigns with key metrics.
**Business Value:**
* Identify top-performing campaigns by spend efficiency
* Compare campaign objectives and their results
* Optimize budget allocation across campaigns
```sql theme={null}
WITH
campaign_metrics AS (
SELECT
c.campaign_name,
c.objective_type,
c.operation_status,
c.budget_mode,
SUM(TRY_CAST(r.spend AS DOUBLE)) AS total_spend,
SUM(TRY_CAST(r.impressions AS BIGINT)) AS total_impressions,
SUM(TRY_CAST(r.clicks AS BIGINT)) AS total_clicks,
SUM(TRY_CAST(r.reach AS BIGINT)) AS total_reach,
SUM(TRY_CAST(r.conversion AS BIGINT)) AS total_conversions,
SUM(TRY_CAST(r.result AS BIGINT)) AS total_results
FROM
nekt_raw.tiktok_ads_campaigns c
LEFT JOIN nekt_raw.tiktok_ads_campaigns_daily_report r
ON c.campaign_id = r.campaign_id
WHERE
date_parse(r.stat_time_day, '%Y-%m-%d') >= CURRENT_DATE - INTERVAL '30' DAY
GROUP BY
c.campaign_name,
c.objective_type,
c.operation_status,
c.budget_mode
)
SELECT
campaign_name,
objective_type,
operation_status,
total_spend,
total_impressions,
total_clicks,
total_reach,
total_conversions,
total_results,
ROUND(total_clicks * 100.0 / NULLIF(total_impressions, 0), 2) AS ctr,
ROUND(total_spend / NULLIF(total_clicks, 0), 2) AS cpc,
ROUND(total_spend / NULLIF(total_conversions, 0), 2) AS cpa
FROM
campaign_metrics
ORDER BY
total_spend DESC
```
```sql theme={null}
WITH
campaign_metrics AS (
SELECT
c.campaign_name,
c.objective_type,
c.operation_status,
c.budget_mode,
SUM(SAFE_CAST(r.spend AS FLOAT64)) AS total_spend,
SUM(SAFE_CAST(r.impressions AS INT64)) AS total_impressions,
SUM(SAFE_CAST(r.clicks AS INT64)) AS total_clicks,
SUM(SAFE_CAST(r.reach AS INT64)) AS total_reach,
SUM(SAFE_CAST(r.conversion AS INT64)) AS total_conversions,
SUM(SAFE_CAST(r.result AS INT64)) AS total_results
FROM
`nekt_raw.tiktok_ads_campaigns` c
LEFT JOIN `nekt_raw.tiktok_ads_campaigns_daily_report` r
ON c.campaign_id = r.campaign_id
WHERE
PARSE_DATE('%Y-%m-%d', r.stat_time_day) >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
GROUP BY
c.campaign_name,
c.objective_type,
c.operation_status,
c.budget_mode
)
SELECT
campaign_name,
objective_type,
operation_status,
total_spend,
total_impressions,
total_clicks,
total_reach,
total_conversions,
total_results,
ROUND(SAFE_DIVIDE(total_clicks * 100.0, total_impressions), 2) AS ctr,
ROUND(SAFE_DIVIDE(total_spend, total_clicks), 2) AS cpc,
ROUND(SAFE_DIVIDE(total_spend, total_conversions), 2) AS cpa
FROM
campaign_metrics
ORDER BY
total_spend DESC
```
| campaign\_name | objective\_type | operation\_status | total\_spend | total\_impressions | total\_clicks | total\_reach | total\_conversions | total\_results | ctr | cpc | cpa |
| -------------------- | --------------- | ----------------- | ------------ | ------------------ | ------------- | ------------ | ------------------ | -------------- | ---- | ---- | ----- |
| Holiday Promo 2024 | CONVERSIONS | ENABLE | 12,450.00 | 2,890,000 | 45,600 | 1,850,000 | 1,230 | 1,230 | 1.58 | 0.27 | 10.12 |
| Brand Awareness Q4 | REACH | ENABLE | 8,200.00 | 5,420,000 | 28,400 | 3,150,000 | 0 | 3,150,000 | 0.52 | 0.29 | - |
| App Install Campaign | APP\_INSTALL | ENABLE | 6,780.00 | 1,560,000 | 38,900 | 980,000 | 2,340 | 2,340 | 2.49 | 0.17 | 2.90 |
| Product Launch | TRAFFIC | ENABLE | 4,320.00 | 890,000 | 22,100 | 620,000 | 0 | 22,100 | 2.48 | 0.20 | - |
### 2. Video Engagement Analysis
Analyze video ad performance to understand viewer engagement patterns.
**Business Value:**
* Identify which video creatives capture attention
* Understand viewer drop-off points
* Optimize video length and content strategy
```sql theme={null}
SELECT
a.ad_name,
a.ad_format,
SUM(TRY_CAST(r.video_play_actions AS BIGINT)) AS total_plays,
SUM(TRY_CAST(r.video_watched_2s AS BIGINT)) AS watched_2s,
SUM(TRY_CAST(r.video_watched_6s AS BIGINT)) AS watched_6s,
SUM(TRY_CAST(r.video_views_p25 AS BIGINT)) AS views_25pct,
SUM(TRY_CAST(r.video_views_p50 AS BIGINT)) AS views_50pct,
SUM(TRY_CAST(r.video_views_p75 AS BIGINT)) AS views_75pct,
SUM(TRY_CAST(r.video_views_p100 AS BIGINT)) AS views_100pct,
AVG(TRY_CAST(r.average_video_play AS DOUBLE)) AS avg_watch_time,
ROUND(
SUM(TRY_CAST(r.video_views_p100 AS DOUBLE)) * 100.0 /
NULLIF(SUM(TRY_CAST(r.video_play_actions AS DOUBLE)), 0), 2
) AS completion_rate
FROM
nekt_raw.tiktok_ads_ads a
LEFT JOIN nekt_raw.tiktok_ads_ads_daily_report r ON a.ad_id = r.ad_id
WHERE
date_parse(r.stat_time_day, '%Y-%m-%d') >= CURRENT_DATE - INTERVAL '30' DAY
AND a.video_id IS NOT NULL
GROUP BY
a.ad_name,
a.ad_format
ORDER BY
total_plays DESC
LIMIT 20
```
```sql theme={null}
SELECT
a.ad_name,
a.ad_format,
SUM(SAFE_CAST(r.video_play_actions AS INT64)) AS total_plays,
SUM(SAFE_CAST(r.video_watched_2s AS INT64)) AS watched_2s,
SUM(SAFE_CAST(r.video_watched_6s AS INT64)) AS watched_6s,
SUM(SAFE_CAST(r.video_views_p25 AS INT64)) AS views_25pct,
SUM(SAFE_CAST(r.video_views_p50 AS INT64)) AS views_50pct,
SUM(SAFE_CAST(r.video_views_p75 AS INT64)) AS views_75pct,
SUM(SAFE_CAST(r.video_views_p100 AS INT64)) AS views_100pct,
AVG(SAFE_CAST(r.average_video_play AS FLOAT64)) AS avg_watch_time,
ROUND(
SAFE_DIVIDE(
SUM(SAFE_CAST(r.video_views_p100 AS FLOAT64)) * 100.0,
SUM(SAFE_CAST(r.video_play_actions AS FLOAT64))
), 2
) AS completion_rate
FROM
`nekt_raw.tiktok_ads_ads` a
LEFT JOIN `nekt_raw.tiktok_ads_ads_daily_report` r ON a.ad_id = r.ad_id
WHERE
PARSE_DATE('%Y-%m-%d', r.stat_time_day) >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
AND a.video_id IS NOT NULL
GROUP BY
a.ad_name,
a.ad_format
ORDER BY
total_plays DESC
LIMIT 20
```
| ad\_name | ad\_format | total\_plays | watched\_2s | watched\_6s | views\_25pct | views\_50pct | views\_75pct | views\_100pct | avg\_watch\_time | completion\_rate |
| ------------------ | ------------- | ------------ | ----------- | ----------- | ------------ | ------------ | ------------ | ------------- | ---------------- | ---------------- |
| Holiday Sale Video | SINGLE\_VIDEO | 458,000 | 412,000 | 298,000 | 356,000 | 245,000 | 178,000 | 89,000 | 8.5 | 19.43 |
| Product Demo 15s | SINGLE\_VIDEO | 234,000 | 218,000 | 189,000 | 201,000 | 167,000 | 134,000 | 112,000 | 12.3 | 47.86 |
| UGC Style Ad | SINGLE\_VIDEO | 189,000 | 178,000 | 156,000 | 168,000 | 145,000 | 123,000 | 98,000 | 14.2 | 51.85 |
### 3. Audience Demographics Analysis
Understand which demographics perform best for your campaigns.
**Business Value:**
* Identify high-value audience segments
* Optimize targeting based on performance data
* Allocate budget to best-performing demographics
```sql theme={null}
SELECT
age,
gender,
SUM(TRY_CAST(spend AS DOUBLE)) AS total_spend,
SUM(TRY_CAST(impressions AS BIGINT)) AS total_impressions,
SUM(TRY_CAST(clicks AS BIGINT)) AS total_clicks,
SUM(TRY_CAST(conversion AS BIGINT)) AS total_conversions,
ROUND(SUM(TRY_CAST(clicks AS DOUBLE)) * 100.0 /
NULLIF(SUM(TRY_CAST(impressions AS DOUBLE)), 0), 2) AS ctr,
ROUND(SUM(TRY_CAST(spend AS DOUBLE)) /
NULLIF(SUM(TRY_CAST(conversion AS DOUBLE)), 0), 2) AS cpa
FROM
nekt_raw.tiktok_ads_ads_age_gender_report
WHERE
date_parse(stat_time_day, '%Y-%m-%d') >= CURRENT_DATE - INTERVAL '30' DAY
GROUP BY
age,
gender
ORDER BY
total_spend DESC
```
```sql theme={null}
SELECT
age,
gender,
SUM(SAFE_CAST(spend AS FLOAT64)) AS total_spend,
SUM(SAFE_CAST(impressions AS INT64)) AS total_impressions,
SUM(SAFE_CAST(clicks AS INT64)) AS total_clicks,
SUM(SAFE_CAST(conversion AS INT64)) AS total_conversions,
ROUND(SAFE_DIVIDE(SUM(SAFE_CAST(clicks AS FLOAT64)) * 100.0,
SUM(SAFE_CAST(impressions AS FLOAT64))), 2) AS ctr,
ROUND(SAFE_DIVIDE(SUM(SAFE_CAST(spend AS FLOAT64)),
SUM(SAFE_CAST(conversion AS FLOAT64))), 2) AS cpa
FROM
`nekt_raw.tiktok_ads_ads_age_gender_report`
WHERE
PARSE_DATE('%Y-%m-%d', stat_time_day) >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
GROUP BY
age,
gender
ORDER BY
total_spend DESC
```
| age | gender | total\_spend | total\_impressions | total\_clicks | total\_conversions | ctr | cpa |
| ----------- | ------ | ------------ | ------------------ | ------------- | ------------------ | ---- | ---- |
| AGE\_18\_24 | FEMALE | 4,560.00 | 1,234,000 | 28,900 | 890 | 2.34 | 5.12 |
| AGE\_25\_34 | FEMALE | 4,120.00 | 1,089,000 | 24,500 | 756 | 2.25 | 5.45 |
| AGE\_18\_24 | MALE | 3,890.00 | 1,156,000 | 21,300 | 612 | 1.84 | 6.35 |
| AGE\_25\_34 | MALE | 3,450.00 | 945,000 | 18,700 | 534 | 1.98 | 6.46 |
| AGE\_35\_44 | FEMALE | 2,780.00 | 678,000 | 14,200 | 423 | 2.09 | 6.57 |
## Implementation Notes
### Data Quality Considerations
* TikTok Ads data may be updated retroactively for up to 7 days. Use the lookback window configuration to ensure data accuracy.
* Real-time metrics (`real_time_conversion`, `real_time_result`) may differ from final metrics as they are reported before full attribution.
* SKAN metrics are only available for iOS campaigns and may have delays due to Apple's SKAdNetwork limitations.
### API Limits & Performance
* TikTok's API has rate limits. For large accounts with many campaigns, extraction may take longer.
* Hourly reports generate more data than daily reports. Select only the granularity you need.
* Audience breakdown reports (age/gender, country, platform) multiply the data volume. Enable only when needed for analysis.
### Best Practices
* Start with daily reports for trend analysis, use hourly only when intraday optimization is needed.
* Use the `include_deleted` option judiciously - excluding deleted entities reduces data volume.
* For e-commerce campaigns, combine page event reports with basic metrics for full funnel visibility.
* For app campaigns, use in-app event reports to track post-install events and LTV.
## Skills for agents
TikTok Ads connector documentation as plain markdown, for use in AI agent contexts.