Lucen

TikTok Ads data reference

Advertising
10 tables
195 columns

Lucen syncs your TikTok Ads data (Advertising) to your warehouse and models it into the tables below. You connect TikTok Ads with one OAuth sign-in. By default your data refreshes every day at 07:00 Buenos Aires time (UTC-3). Your plan sets how many times a day it can sync, and you can choose the times, see pricing.

Your plan sets how much history the first sync loads, see pricing.

Send TikTok Ads data to

Tables

gold_tiktok_ads_account_performance

Grain
none. Native daily reach / frequency

gold_tiktok_ads_ad_group_performance

Grain
campaign + ad group

gold_tiktok_ads_ad_performance

Grain
campaign + ad group + ad

gold_tiktok_ads_age_performance

Grain
age

gold_tiktok_ads_campaign_performance

Grain
campaign

gold_tiktok_ads_conversion_event_performance

Grain
ad + event type. No spend

gold_tiktok_ads_device_performance

Grain
device platform

gold_tiktok_ads_gender_performance

Grain
gender

gold_tiktok_ads_geo_performance

Grain
country

gold_tiktok_ads_placement_performance

Grain
placement

Columns

Column names match your warehouse exactly. Descriptions come from dbt.

gold_tiktok_ads_account_performance columns

17

gold_tiktok_ads_ad_group_performance columns

23

gold_tiktok_ads_ad_performance columns

42

gold_tiktok_ads_age_performance columns

IDNameTypeDescription
account_idAccount idSTRINGTikTok advertiser ID. Use with client_id to scope joins and reporting.
client_idClient idSTRINGLucen organization slug. Include in every join to preserve tenant isolation.
currencyCurrencySTRINGAdvertiser currency code; monetary metrics are not currency-converted.
timezone_nameTimezone nameSTRINGAdvertiser timezone used to define report dates and snapshot dates.
dateDateDATEReporting day in the advertiser timezone, using standard TikTok attribution reporting.
ageAgeSTRINGNative audience-report age category; independent of gender and other breakdowns.
spendSpendFLOAT64Ad spend in advertiser currency. Sum within one fact and currency.
impressionsImpressionsFLOAT64Number of ad impressions; repeat exposure is included.
destination_clicksDestination clicksFLOAT64Clicks to the ad destination (TikTok clicks); excludes other engagement clicks.
account_nameAccount nameSTRINGAdvertiser name from the retrieved account metadata.
data_updated_atData updated atTIMESTAMPUTC extraction timestamp of the underlying performance row, not the table build time.
destination_ctrDestination ctrFLOAT64Destination clicks / impressions as a decimal fraction; NULL for zero impressions. Recompute from summed components.
destination_cpcDestination cpcFLOAT64Spend / destination clicks in advertiser currency; NULL for zero clicks. Recompute from summed components.
cpmCpmFLOAT641,000 * spend / impressions in advertiser currency; NULL for zero impressions. Recompute from summed components.

gold_tiktok_ads_campaign_performance columns

22

gold_tiktok_ads_conversion_event_performance columns

21

gold_tiktok_ads_device_performance columns

IDNameTypeDescription
account_idAccount idSTRINGTikTok advertiser ID. Use with client_id to scope joins and reporting.
client_idClient idSTRINGLucen organization slug. Include in every join to preserve tenant isolation.
currencyCurrencySTRINGAdvertiser currency code; monetary metrics are not currency-converted.
timezone_nameTimezone nameSTRINGAdvertiser timezone used to define report dates and snapshot dates.
dateDateDATEReporting day in the advertiser timezone, using standard TikTok attribution reporting.
platformPlatformSTRINGNative audience-report device platform category; not a device model or device_type field.
spendSpendFLOAT64Ad spend in advertiser currency. Sum within one fact and currency.
impressionsImpressionsFLOAT64Number of ad impressions; repeat exposure is included.
destination_clicksDestination clicksFLOAT64Clicks to the ad destination (TikTok clicks); excludes other engagement clicks.
account_nameAccount nameSTRINGAdvertiser name from the retrieved account metadata.
data_updated_atData updated atTIMESTAMPUTC extraction timestamp of the underlying performance row, not the table build time.
destination_ctrDestination ctrFLOAT64Destination clicks / impressions as a decimal fraction; NULL for zero impressions. Recompute from summed components.
destination_cpcDestination cpcFLOAT64Spend / destination clicks in advertiser currency; NULL for zero clicks. Recompute from summed components.
cpmCpmFLOAT641,000 * spend / impressions in advertiser currency; NULL for zero impressions. Recompute from summed components.

gold_tiktok_ads_gender_performance columns

IDNameTypeDescription
account_idAccount idSTRINGTikTok advertiser ID. Use with client_id to scope joins and reporting.
client_idClient idSTRINGLucen organization slug. Include in every join to preserve tenant isolation.
currencyCurrencySTRINGAdvertiser currency code; monetary metrics are not currency-converted.
timezone_nameTimezone nameSTRINGAdvertiser timezone used to define report dates and snapshot dates.
dateDateDATEReporting day in the advertiser timezone, using standard TikTok attribution reporting.
genderGenderSTRINGNative audience-report gender category; independent of age and other breakdowns.
spendSpendFLOAT64Ad spend in advertiser currency. Sum within one fact and currency.
impressionsImpressionsFLOAT64Number of ad impressions; repeat exposure is included.
destination_clicksDestination clicksFLOAT64Clicks to the ad destination (TikTok clicks); excludes other engagement clicks.
account_nameAccount nameSTRINGAdvertiser name from the retrieved account metadata.
data_updated_atData updated atTIMESTAMPUTC extraction timestamp of the underlying performance row, not the table build time.
destination_ctrDestination ctrFLOAT64Destination clicks / impressions as a decimal fraction; NULL for zero impressions. Recompute from summed components.
destination_cpcDestination cpcFLOAT64Spend / destination clicks in advertiser currency; NULL for zero clicks. Recompute from summed components.
cpmCpmFLOAT641,000 * spend / impressions in advertiser currency; NULL for zero impressions. Recompute from summed components.

gold_tiktok_ads_geo_performance columns

IDNameTypeDescription
account_idAccount idSTRINGTikTok advertiser ID. Use with client_id to scope joins and reporting.
client_idClient idSTRINGLucen organization slug. Include in every join to preserve tenant isolation.
currencyCurrencySTRINGAdvertiser currency code; monetary metrics are not currency-converted.
timezone_nameTimezone nameSTRINGAdvertiser timezone used to define report dates and snapshot dates.
dateDateDATEReporting day in the advertiser timezone, using standard TikTok attribution reporting.
country_codeCountry codeSTRINGNative audience-report country code. Coverage may differ from account totals.
spendSpendFLOAT64Ad spend in advertiser currency. Sum within one fact and currency.
impressionsImpressionsFLOAT64Number of ad impressions; repeat exposure is included.
destination_clicksDestination clicksFLOAT64Clicks to the ad destination (TikTok clicks); excludes other engagement clicks.
account_nameAccount nameSTRINGAdvertiser name from the retrieved account metadata.
data_updated_atData updated atTIMESTAMPUTC extraction timestamp of the underlying performance row, not the table build time.
destination_ctrDestination ctrFLOAT64Destination clicks / impressions as a decimal fraction; NULL for zero impressions. Recompute from summed components.
destination_cpcDestination cpcFLOAT64Spend / destination clicks in advertiser currency; NULL for zero clicks. Recompute from summed components.
cpmCpmFLOAT641,000 * spend / impressions in advertiser currency; NULL for zero impressions. Recompute from summed components.

gold_tiktok_ads_placement_performance columns

IDNameTypeDescription
account_idAccount idSTRINGTikTok advertiser ID. Use with client_id to scope joins and reporting.
client_idClient idSTRINGLucen organization slug. Include in every join to preserve tenant isolation.
currencyCurrencySTRINGAdvertiser currency code; monetary metrics are not currency-converted.
timezone_nameTimezone nameSTRINGAdvertiser timezone used to define report dates and snapshot dates.
dateDateDATEReporting day in the advertiser timezone, using standard TikTok attribution reporting.
placementPlacementSTRINGNative audience-report placement category; no campaign or ad attribution is published at this grain.
spendSpendFLOAT64Ad spend in advertiser currency. Sum within one fact and currency.
impressionsImpressionsFLOAT64Number of ad impressions; repeat exposure is included.
destination_clicksDestination clicksFLOAT64Clicks to the ad destination (TikTok clicks); excludes other engagement clicks.
account_nameAccount nameSTRINGAdvertiser name from the retrieved account metadata.
data_updated_atData updated atTIMESTAMPUTC extraction timestamp of the underlying performance row, not the table build time.
destination_ctrDestination ctrFLOAT64Destination clicks / impressions as a decimal fraction; NULL for zero impressions. Recompute from summed components.
destination_cpcDestination cpcFLOAT64Spend / destination clicks in advertiser currency; NULL for zero clicks. Recompute from summed components.
cpmCpmFLOAT641,000 * spend / impressions in advertiser currency; NULL for zero impressions. Recompute from summed components.

Typical questions

Prompt to try
Account spend / reach

gold_tiktok_ads_account_performance

Prompt to try
Campaign ranking

gold_tiktok_ads_campaign_performance

Prompt to try
Website purchases

gold_tiktok_ads_conversion_event_performancefiltered to website_purchase

Starter queries

sql
SELECT date, account_id, currency, timezone_name, spend
FROM `your-project.your_org_gold.gold_tiktok_ads_account_performance`
WHERE date >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
ORDER BY date DESC
LIMIT 100;
sql
SELECT date, account_id, currency, timezone_name, campaign_id
FROM `your-project.your_org_gold.gold_tiktok_ads_campaign_performance`
WHERE date >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
ORDER BY date DESC
LIMIT 100;
sql
SELECT date, account_id, currency, timezone_name, campaign_id
FROM `your-project.your_org_gold.gold_tiktok_ads_ad_group_performance`
WHERE date >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
ORDER BY date DESC
LIMIT 100;
sql
SELECT date, account_id, currency, timezone_name, campaign_id
FROM `your-project.your_org_gold.gold_tiktok_ads_ad_performance`
WHERE date >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
ORDER BY date DESC
LIMIT 100;

Integration page