Configuring TikTok Ads as a Source
In the 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 theTikTok 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.
- 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.
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.
4. Configure data source
Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, 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. 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 page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.Streams and Fields
Below you’ll find all available data streams from TikTok Ads and their corresponding fields:Ad Accounts
Ad Accounts
advertiser_id- Unique identifier for the advertiser accountname- Name of the advertiser accountcompany- Company namebalance- Account balancecurrency- Account currencytimezone- Account timezonedisplay_timezone- Display timezone settingstatus- Account statusrole- User role in the account
email- Contact emailtelephone- Contact telephonephonenumber- Contact phone numbercontacter- Contact person nameaddress- Business addresscountry- Country
industry- Industry categorybrand- Brand namedescription- Account descriptionpromotion_area- Promotion areapromotion_center_city- Promotion center citypromotion_center_province- Promotion center provincecreate_time- Account creation timestamplanguage- Account languageowner_bc_id- Owner business center ID
license_no- License numberlicense_url- License URLlicense_city- License citylicense_province- License province
Campaigns
Campaigns
campaign_id- Unique identifier for the campaigncampaign_name- Name of the campaignadvertiser_id- ID of the advertiser accountobjective_type- Campaign objective typeoperation_status- Operational status (e.g., ENABLE, DISABLE)secondary_status- Secondary status detailscreate_time- Campaign creation timemodify_time- Last modification time
campaign_type- Type of campaigncampaign_system_origin- System origin of the campaignis_search_campaign- Whether it’s a search campaignis_smart_performance_campaign- Whether smart performance is enabledis_advanced_dedicated_campaign- Whether advanced dedicated campaignis_new_structure- Whether using new structure
budget- Campaign budgetbudget_mode- Budget mode (BUDGET_MODE_DAY, BUDGET_MODE_TOTAL)budget_optimize_on- Budget optimization settingbid_type- Bid typedeep_bid_type- Deep bid typeroas_bid- ROAS bid valueoptimization_goal- Optimization goal
app_id- Associated app IDapp_promotion_type- App promotion typecampaign_app_profile_page_state- App profile page statecampaign_product_source- Product source
special_industries- Array of special industry categoriesrf_campaign_type- Reach & Frequency campaign typerta_id- RTA IDrta_product_selection_enabled- RTA product selection statuspostback_window_mode- Postback window modeobjective- Campaign objective
Ad Groups
Ad Groups
adgroup_id- Unique identifier for the ad groupadgroup_name- Name of the ad groupcampaign_id- Parent campaign IDcampaign_name- Parent campaign nameadvertiser_id- Advertiser account IDoperation_status- Operational statussecondary_status- Secondary status detailscreate_time- Creation timemodify_time- Last modification time
location_ids- Targeted location IDszipcode_ids- Targeted zipcode IDslanguages- Targeted languagesgender- Targeted genderage_groups- Targeted age groupsspending_power- Spending power targetinghousehold_income- Household income targetingaudience_ids- Custom audience IDsexcluded_audience_ids- Excluded audience IDsinterest_category_ids- Interest category IDsinterest_keyword_ids- Interest keyword IDspurchase_intention_keyword_ids- Purchase intention keyword IDs
budget- Ad group budgetbudget_mode- Budget modescheduled_budget- Scheduled budgetbid_type- Bid typebid_price- Bid priceconversion_bid_price- Conversion bid pricedeep_bid_type- Deep bid typedeep_cpa_bid- Deep CPA bidroas_bid- ROAS bid
schedule_type- Schedule typeschedule_start_time- Schedule start timeschedule_end_time- Schedule end timedayparting- Dayparting schedule
placement_type- Placement typeplacements- Array of placementsoptimization_goal- Optimization goaloptimization_event- Optimization eventbilling_event- Billing eventpacing- Pacing settingdelivery_mode- Delivery mode
operating_systems- Targeted operating systemsmin_android_version- Minimum Android versionmin_ios_version- Minimum iOS versionios14_targeting- iOS 14+ targeting settingdevice_model_ids- Targeted device modelsnetwork_types- Targeted network typescarrier_ids- Targeted carrier IDs
click_attribution_window- Click attribution windowview_attribution_window- View attribution windowengaged_view_attribution_window- Engaged view attribution window
shopping_ads_type- Shopping ads typeshopping_ads_retargeting_type- Retargeting typestore_id- Store IDcatalog_id- Catalog ID
Ads
Ads
ad_id- Unique identifier for the adad_name- Name of the adadgroup_id- Parent ad group IDadgroup_name- Parent ad group namecampaign_id- Parent campaign IDcampaign_name- Parent campaign nameadvertiser_id- Advertiser account IDoperation_status- Operational statussecondary_status- Secondary status detailscreate_time- Creation timemodify_time- Last modification time
ad_text- Primary ad textad_texts- Additional ad textsad_format- Ad format typevideo_id- Video asset IDimage_ids- Image asset IDsmusic_id- Music asset IDcarousel_image_index- Carousel image indextiktok_item_id- TikTok item IDcreative_type- Creative type
call_to_action- Call to action textcall_to_action_id- Call to action IDcard_id- Card ID
landing_page_url- Landing page URLdeeplink- Deep link URLdeeplink_type- Deep link typecpp_url- CPP URLpage_id- Page IDdynamic_destination- Dynamic destination setting
tracking_pixel_id- Pixel ID for trackingtracking_app_id- App ID for trackingtracking_offline_event_set_ids- Offline event set IDsimpression_tracking_url- Impression tracking URLclick_tracking_url- Click tracking URLutm_params- UTM parameters array
identity_id- Identity IDidentity_type- Identity typedisplay_name- Display nameprofile_image_url- Profile image URLavatar_icon_web_uri- Avatar icon URI
catalog_id- Catalog IDproduct_set_id- Product set IDsku_ids- SKU IDsitem_group_ids- Item group IDsshowcase_products- Showcase products array
vast_moat_enabled- VAST MOAT enabledviewability_postbid_partner- Viewability partnerbrand_safety_postbid_partner- Brand safety partner
Ads Daily Report
Ads Daily Report
ad_id- Ad identifierstat_time_day- Date of the metrics
spend- Total ad spendbilled_cost- Billed cost (excluding credits/coupons)impressions- Number of ad impressionsgross_impressions- Total impressions including invalidclicks- Number of clicksctr- Click-through ratecpc- Cost per clickcpm- Cost per 1,000 impressionsreach- Unique users reachedcost_per_1000_reached- Cost to reach 1,000 usersfrequency- Average impressions per user
conversion- Number of conversionscost_per_conversion- Cost per conversionconversion_rate_v2- Conversion ratereal_time_conversion- Real-time conversionsreal_time_cost_per_conversion- Real-time CPAreal_time_conversion_rate_v2- Real-time conversion rate
result- Number of results based on objectivecost_per_result- Cost per resultresult_rate- Result ratereal_time_result- Real-time resultsreal_time_cost_per_result- Real-time cost per resultsecondary_goal_result- Secondary goal resultscost_per_secondary_goal_result- Cost per secondary result
video_play_actions- Video play countvideo_watched_2s- 2-second video viewsvideo_watched_6s- 6-second video viewsengaged_view- Engaged views (6s or interaction)engaged_view_15s- 15-second engaged viewsvideo_views_p25- 25% video completion viewsvideo_views_p50- 50% video completion viewsvideo_views_p75- 75% video completion viewsvideo_views_p100- 100% video completion viewsaverage_video_play- Average video play timeaverage_video_play_per_user- Average play time per user
skan_result- SKAdNetwork resultsskan_cost_per_result- SKAN cost per resultskan_conversion- SKAN conversionsskan_cost_per_conversion- SKAN cost per conversion
Ads Hourly Report
Ads Hourly Report
ad_id- Ad identifierstat_time_hour- Hour of the metrics
Ads Reservation Daily Report
Ads Reservation Daily Report
ad_id- Ad identifierstat_time_day- Date of the metrics
Ads Reservation Hourly Report
Ads Reservation Hourly Report
ad_id- Ad identifierstat_time_hour- Hour of the metrics
Ads Age & Gender Report
Ads Age & Gender Report
ad_id- Ad identifierstat_time_day- Date of the metricsage- Age group (e.g., AGE_18_24, AGE_25_34)gender- Gender (MALE, FEMALE)
spend- Total spendimpressions- Impressionsgross_impressions- Gross impressionsclicks- Clicksctr- Click-through ratecpc- Cost per clickcpm- Cost per mille
conversion- Conversionscost_per_conversion- CPAconversion_rate- CVRreal_time_conversion- Real-time conversionsreal_time_cost_per_conversion- Real-time CPAreal_time_conversion_rate- Real-time CVR
result- Resultscost_per_result- Cost per resultresult_rate- Result ratereal_time_result- Real-time resultsreal_time_cost_per_result- Real-time cost per resultreal_time_result_rate- Real-time result rate
Ads Country Report
Ads Country Report
ad_id- Ad identifierstat_time_day- Date of the metricscountry_code- Country code (ISO 2-letter)
Ads Language Report
Ads Language Report
ad_id- Ad identifierstat_time_day- Date of the metricslanguage- User language code
Ads Platform Report
Ads Platform Report
ad_id- Ad identifierstat_time_day- Date of the metricsplatform- Platform (ANDROID, IOS)
Ads Page Event Daily Report
Ads Page Event Daily Report
ad_id- Ad identifierstat_time_day- Date of the metrics
complete_payment- Complete payment eventscost_per_complete_payment- Cost per paymentcomplete_payment_rate- Payment ratevalue_per_complete_payment- Value per paymentcomplete_payment_roas- Payment ROAS
user_registration- Registration eventscost_per_user_registration- Cost per registrationuser_registration_rate- Registration ratevalue_per_user_registration- Value per registration
product_details_page_browse- Product page viewscost_per_product_details_page_browse- Cost per viewproduct_details_page_browse_rate- View rate
web_event_add_to_cart- Add to cart eventscost_per_web_event_add_to_cart- Cost per add to cartweb_event_add_to_cart_rate- Add to cart rate
initiate_checkout- Checkout initiationscost_per_initiate_checkout- Cost per checkoutinitiate_checkout_rate- Checkout rate
on_web_add_to_wishlist- Add to wishlist eventscost_per_on_web_add_to_wishlist- Cost per wishlist add
Ads In-App Event Daily Report
Ads In-App Event Daily Report
ad_id- Ad identifierstat_time_day- Date of the metrics
purchase- In-app purchasescost_per_purchase- Cost per purchasepurchase_rate- Purchase ratetotal_purchase- Total purchasestotal_purchase_value- Total purchase valuetotal_active_pay_roas- Purchase ROAS
checkout- App checkout eventscost_per_checkout- Cost per checkoutcheckout_rate- Checkout ratetotal_checkout_value- Total checkout value
view_content- View content eventscost_per_view_content- Cost per viewview_content_rate- View rate
app_event_add_to_cart- App add to cartcost_per_app_event_add_to_cart- Cost per add to cartapp_event_add_to_cart_rate- Add to cart rate
add_to_wishlist- Add to wishlist eventscost_per_add_to_wishlist- Cost per wishlist addadd_to_wishlist_rate- Wishlist rate
Ads Page Event Reservation Daily Report
Ads Page Event Reservation Daily Report
ad_id- Ad identifierstat_time_day- Date of the metrics
Ads In-App Event Reservation Daily Report
Ads In-App Event Reservation Daily Report
ad_id- Ad identifierstat_time_day- Date of the metrics
Ad Groups Daily Report
Ad Groups Daily Report
adgroup_id- Ad group identifierstat_time_day- Date of the metrics
Ad Groups Hourly Report
Ad Groups Hourly Report
adgroup_id- Ad group identifierstat_time_hour- Hour of the metrics
Ad Groups Reservation Daily Report
Ad Groups Reservation Daily Report
adgroup_id- Ad group identifierstat_time_day- Date of the metrics
Ad Groups Reservation Hourly Report
Ad Groups Reservation Hourly Report
adgroup_id- Ad group identifierstat_time_hour- Hour of the metrics
Campaigns Daily Report
Campaigns Daily Report
campaign_id- Campaign identifierstat_time_day- Date of the metrics
Campaigns Hourly Report
Campaigns Hourly Report
campaign_id- Campaign identifierstat_time_hour- Hour of the metrics
Campaigns Reservation Daily Report
Campaigns Reservation Daily Report
campaign_id- Campaign identifierstat_time_day- Date of the metrics
Campaigns Reservation Hourly Report
Campaigns Reservation Hourly Report
campaign_id- Campaign identifierstat_time_hour- Hour of the metrics
Campaigns Age & Gender Report
Campaigns Age & Gender Report
campaign_id- Campaign identifierstat_time_day- Date of the metricsage- Age group (e.g., AGE_18_24, AGE_25_34)gender- Gender (MALE, FEMALE)
Campaigns Country Report
Campaigns Country Report
campaign_id- Campaign identifierstat_time_day- Date of the metricscountry_code- Country code (ISO 2-letter)
Campaigns Language Report
Campaigns Language Report
campaign_id- Campaign identifierstat_time_day- Date of the metricslanguage- User language code
Campaigns Platform Report
Campaigns Platform Report
campaign_id- Campaign identifierstat_time_day- Date of the metricsplatform- Platform (ANDROID, IOS)
Campaigns Page Event Daily Report
Campaigns Page Event Daily Report
campaign_id- Campaign identifierstat_time_day- Date of the metrics
Campaigns Page Event Reservation Daily Report
Campaigns Page Event Reservation Daily Report
campaign_id- Campaign identifierstat_time_day- Date of the metrics
Campaigns In-App Event Daily Report
Campaigns In-App Event Daily Report
campaign_id- Campaign identifierstat_time_day- Date of the metrics
Campaigns In-App Event Reservation Daily Report
Campaigns In-App Event Reservation Daily Report
campaign_id- Campaign identifierstat_time_day- Date of the metrics
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.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.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 query
SQL query
- AWS
- GCP
Sample Result
Sample Result
| 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 query
SQL query
- AWS
- GCP
Sample Result
Sample Result
| 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 query
SQL query
- AWS
- GCP
Sample Result
Sample Result
| 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_deletedoption 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.