TikTok Ads Field Reference

Sample

 

https://connectors.windsor.ai/tiktok?api_key=[your API key]&date_preset=last_7d&fields=campaign,clicks,spend,impressions,date,source&_renderer=csv


Fields

IDTypeNameDescriptionReport
acTEXTacGroup by networkac
account_idTEXTAccount IDThe TikTok Ads account IDAccount
account_nameTEXTAccount NameThe TikTok Ads account nameAccount
ad_group_idTEXTAd Group IDAd group IDAd
ad_group_nameTEXTAd Group NameAd group nameAd
ad_idTEXTAd IDAd IDAd
ad_nameTEXTAd NameAd NameAd
ad_textTEXTAd titleSupported at Ad level.
aeo_typeTEXTApp Event Optimization TypeSupported at Ad Group and Ad level.
ageTEXTAge RangeThe Age Range of the AudiencePerformance
app_installNUMERICApp InstallThe number of times your mobile app was installed that were recorded as app events and attributed to your ads. (The total count is calculated based on the time each ad impression occurred.)Performance
average_video_playNUMERICVideo Average Watch Time Per Video ViewThe average time your video was played per single video view, including any time spent replaying the video.Video
average_video_play_per_userNUMERICVideo Average Watch Time Per PersonThe average time your video was played per person, including any time spent replaying the video. This metric is estimated.Video
bidTEXTBidSupported at Ad Group and Ad level.
bid_strategyTEXTBid strategySupported at Ad Group and Ad level.
billing_eventTEXTBilling EventSupported at Ad Group and Ad level.Example: `Clicks`, `Impression`.
budgetTEXTAd group budgetSupported at Ad Group and Ad level.
budget_optimize_switchTEXTBudget Optimize SwitchWhether Campaign Budget Optimization (CBO) is enabledCampaign
call_to_actionTEXTCall To ActionCall-to-action (CTA)Ad
call_to_action_idTEXTCall To Action ID (deprecated)Call-to-action (CTA) IDAd
campaignTEXTCampaignThe Campaign NameCampaign
campaign_bid_typeTEXTCampaign Bid TypeBidding strategy on the campaign level.Campaign
campaign_budgetNUMERICCampaign BudgetCampaign budgetCampaign
campaign_budget_typeTEXTCampaign Budget Type (deprecated)Campaign budget typeCampaign
campaign_creation_timeTEXTCampaign Creation TimeTime at which campaign was createdCampaign
campaign_deep_bid_typeTEXTCampaign Deep Bid TypeBidding strategy for in-app events. Campaign
campaign_idTEXTCampaign IDThe Campaign IDCampaign
campaign_modify_timeTEXTCampaign Modify Time (deprecated)Time at which campaign was modifiedCampaign
campaign_nameTEXTCampaignThe Campaign Name
campaign_optimize_goalTEXTCampaign Optimize GoalOptimization goal. Returned only if Campaign Busget Optimization is enabled. Campaign
campaign_roas_bidTEXTROAS bidROAS goal for Value Optimization bid strategies (VO_*)Campaign
campaign_typeTEXTCampaign TypeCampaign objectiveCampaign
clicksNUMERICClicksThe Number of ClicksPerformance
commentsNUMERICCommentsThe number of comments your video creative received within 1 day of a user seeing a paid ad.Performance
complete_paymentNUMERICTotal Complete PaymentPage Event Metric. The number of complete payment events.Performance
conversionNUMERICConversionThe number of times your ad achieved an outcome, based on the secondary goal you selected. (Duplicate)Performance
conversion_ratePERCENTConversion RateThe number of conversions and divided by the number of total ad interactions that can be tracked to a conversion.Performance
conversionsNUMERICConversionsThe number of times your ad achieved an outcome, based on the secondary goal you selected.Performance
cost_per_app_installNUMERICCost per App InstallThe average cost for each app install event. (The total count is calculated based on the time each ad impression occurred.)Performance
cost_per_conversionNUMERICCost per conversionThe cost (Spend) divided by the conversions your ad generates(Conversions)Performance
cost_per_create_groupNUMERICCost per Unique Create Group The average cost for each unique create group event that is attributed toyour ads. (The total count is calculated based on the time each ad impression occurred.)Performance
cost_per_registrationNUMERICCost per Unique RegistrationThe average cost for each unique registration that is attributed to your ad. (The total count is calculated based on the time each ad impression occurred.)Performance
cost_per_total_create_groupNUMERICCost per Create Group Cost per Create Group (The total count is based on when you were billed.) Performance
cost_per_total_registrationNUMERICCost per RegistrationCost per Registration (The total count is based on when you were billed.)Performance
countryCOUNTRYCountryThe code of Country of the Audience
cpcNUMERICCPCThe cost (Spend) divided by the clicks your ad receives(Clicks)Performance
create_groupNUMERICCost per Unique Create GroupThe average cost for each unique create group event that is attributed toyour ads. (The total count is calculated based on the time each adimpression occurred.) Performance
create_group_rateNUMERICCreate Group Rate (%) The percentage of unique create group events out of all app install events. (The total count is calculated based on the time each ad impression occurred.) Performance
ctrPERCENTCTRThe number of clicks your ad receives (Clicks) divided by the number of times your ad is shown (Impressions).Performance
currencyTEXTCurrencyThe currency code, e.g. USD.Account
dateDATEDateThe DateTime
dpa_target_audience_typeTEXTTarget audience type for DPAThe Audience that DPA products target
followsNUMERICFollowsThe number of new followers that were gained within 1 day of a user seeing a paid ad. This metric is only for Boosted TikToks.Performance
frequencyNUMERICFrequencyThe average number of times each person saw your ad.(Conversions)Performance
genderTEXTGenderThe Gender of the Audience
image_modeTEXTFormatSupported at Campaign, Ad Group and Ad level.
impressionsNUMERICImpressionsThe Number of ImpressionsPerformance
initiate_checkoutNUMERICTotal Initiate CheckoutPage Event Metric. The number of initiate checkout events.Performance
is_automated_adTEXTIs Automated ADWhether the ad is automated.Ad
languageTEXTLanguageThe Language of the AudienceAudience
likesNUMERICLikesThe number of likes your video creative received within 1 day of a user seeing a paid ad.Performance
mobile_app_idTEXTMobile App IDSupported at Ad Group and Ad level. Returned if the promotion type of one Ad Group is App.
objectiveTEXTObjectiveCampaign type. Possible values: APP, LANDING_PAGECampaign
objective_typeTEXTObjective TypeAdvertising objectiveCampaign
opt_statusTEXTAutomated creative optimizationAutomated creative optimization
placementTEXTPlacementThe Placement Name
placement_typeTEXTPlacement typeThe Placement type
platformTEXTPlatformThe Operating System of the Audience
play_duration_2sNUMERIC2-Second Video ViewsThe number of times your video played for at least 2 seconds. Replays will not be counted.Video
play_duration_6sNUMERIC6-Second Video ViewsThe number of times your video played for at least 6 seconds, or completely played. Replays will not be counted.Video
play_first_quartileNUMERICVideo Views at 25%The number of times your video was played at 25% of its length. Replays will not be counted.Video
play_midpointNUMERICVideo Views at 50%The number of times your video was played at 50% of its length. Replays will not be counted.Video
play_overNUMERICVideo Views at 100%The number of times your video was played at 100% of its length. Replays will not be counted.Video
play_third_quartileNUMERICVideo Views at 75%The number of times your video was played at 75% of its length. Replays will not be counted.Video
promotion_typeTEXTPromotion typeThe promotion type
purchaseNUMERICUnique PurchaseIn-app event metric. The number of unique purchases event occurred in your app that were recorded by your measurement partner. (The total count is calculated based on the time each ad impression occurred.)Performance
purchase_rateNUMERICPurchase Rate (%)In-app event metric. The percentage of unique purchase event out of all the app install event. (The total count is calculated based on the time each ad impression occurred.)Performance
reachNUMERICReachThe number of unique users who saw your ads at least onceReach
real_time_app_installNUMERICReal-time App InstallThe number of times your mobile app was installed that were recorded as app events and attributed to your ads. (The total count is based on when the conversion actually happened.)Performance
real_time_app_install_costNUMERICCost per Real-time App InstallThe average cost for each app install event. (The total count is based on when the conversion actually happened.)Performance
registrationNUMERICUnique RegistrationThe number of unique registrations in your mobile app that were recorded as app events and attributed to your ads. (The total count is calculated based on the time each ad impression occurred.)Performance
registration_rateNUMERICRegistration Rate (%)The percentage of unique registration events out of all app install events. (The total count is calculated based on the time each ad impression occurred.)Performance
sharesNUMERICSharesThe number of shares your video creative received within 1 day of a user seeing a paid ad.Performance
smart_targetTEXTOptimization goalSupported at Ad Group and Ad level.
spendNUMERICspendThe Media SpendPerformance
total_checkoutNUMERICTotal CheckoutIn-app event metric. Checkout (Total No.) (The total count is based on when you were billed.)Performance
total_checkout_valueNUMERICTotal Checkout ValueIn-app event metric. Total Checkout Value (The total count is based on when you were billed.)Performance
total_complete_payment_rateNUMERICTotal Complete Payment ValuePage Event Metric. The total value returned from all Complete Payment events.Performance
total_complete_tutorialNUMERICTotal Complete TutorialThe number of complete tutorial events that are attributed to your ads.Performance
total_complete_tutorial_valueNUMERICTotal Complete Tutorial ValueThe total value returned from all complete tutorial events.Performance
total_create_groupNUMERICTotal Create GroupThe number of create group events that are attributed to your ads.Performance
total_create_group_valueNUMERICTotal Create Group ValueThe total value returned from all create group events.Performance
total_initiate_checkout_valueNUMERICTotal Initiate Checkout ValuePage Event Metric. The total value returned from initiate checkout events.Performance
total_playNUMERICVideo Views (tiktok)The number of times your video starts to play. Replays will not be counted.Video
total_registrationNUMERICTotal RegistrationTotal Registration. The total count is based on when you were billed.Performance
totalcostNUMERICTotal CostThe Media Spend (Duplicate)Performance
tt_app_idTEXTTikTok App ID TikTok App ID, the App ID you used when creating an Ad Group. Supported at Ad Group and Ad level. Returned if the promotion type of one Ad Group is App.
tt_app_nameTEXTTikTok App NameThe name of your TikTok App. Supported at Ad Group and Ad level. Returned if thepromotion type of one Ad Group is App.
value_per_total_create_groupNUMERICValue per Create Group Value per Create Group (The total count is based on when you were billed.) Performance
todayDATETodayToday's date